<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Predicates &mdash; The Logtalk Handbook v3.93.0-b01 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
      <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=396eccfe" />

  
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script src="../_static/jquery.js?v=5d32c60e"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
        <script src="../_static/documentation_options.js?v=c8100655"></script>
        <script src="../_static/doctools.js?v=9a2dae69"></script>
        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/js/theme.js"></script>
    <!-- begin favicon -->
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
    <link rel="manifest" href="/site.webmanifest" />
    <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#5bbad5" />
    <meta name="msapplication-TileColor" content="#355b95" />
    <meta name="theme-color" content="#ffffff" />
    <!-- end favicon -->
    
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Inheritance" href="inheritance.html" />
    <link rel="prev" title="Categories" href="categories.html" />
   
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            The Logtalk Handbook
              <img src="../_static/logtalk.gif" class="logo" alt="Logo"/>
          </a>
              <div class="version">
                3.93.0
              </div>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
    
              <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="index.html">User Manual</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="declarative.html">Declarative object-oriented programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="features.html">Main features</a></li>
<li class="toctree-l2"><a class="reference internal" href="nomenclature.html">Nomenclature</a></li>
<li class="toctree-l2"><a class="reference internal" href="messages.html">Messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="objects.html">Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="protocols.html">Protocols</a></li>
<li class="toctree-l2"><a class="reference internal" href="categories.html">Categories</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Predicates</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#reserved-predicate-names">Reserved predicate names</a></li>
<li class="toctree-l3"><a class="reference internal" href="#declaring-predicates">Declaring predicates</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#scope-directives">Scope directives</a></li>
<li class="toctree-l4"><a class="reference internal" href="#mode-directive">Mode directive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#meta-predicate-directive">Meta-predicate directive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#discontiguous-directive">Discontiguous directive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#dynamic-directive">Dynamic directive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#operator-directive">Operator directive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#uses-directive">Uses directive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#alias-directive">Alias directive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#documenting-directive">Documenting directive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#multifile-directive">Multifile directive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#coinductive-directive">Coinductive directive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#synchronized-directive">Synchronized directive</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#defining-predicates">Defining predicates</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#object-predicates">Object predicates</a></li>
<li class="toctree-l4"><a class="reference internal" href="#category-predicates">Category predicates</a></li>
<li class="toctree-l4"><a class="reference internal" href="#meta-predicates">Meta-predicates</a></li>
<li class="toctree-l4"><a class="reference internal" href="#lambda-expressions">Lambda expressions</a></li>
<li class="toctree-l4"><a class="reference internal" href="#redefining-built-in-predicates">Redefining built-in predicates</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#definite-clause-grammar-rules">Definite clause grammar rules</a></li>
<li class="toctree-l3"><a class="reference internal" href="#built-in-methods">Built-in methods</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#logic-and-control-methods">Logic and control methods</a></li>
<li class="toctree-l4"><a class="reference internal" href="#execution-context-methods">Execution context methods</a></li>
<li class="toctree-l4"><a class="reference internal" href="#error-handling-and-throwing-methods">Error handling and throwing methods</a></li>
<li class="toctree-l4"><a class="reference internal" href="#database-methods">Database methods</a></li>
<li class="toctree-l4"><a class="reference internal" href="#meta-call-methods">Meta-call methods</a></li>
<li class="toctree-l4"><a class="reference internal" href="#all-solutions-methods">All solutions methods</a></li>
<li class="toctree-l4"><a class="reference internal" href="#reflection-methods">Reflection methods</a></li>
<li class="toctree-l4"><a class="reference internal" href="#definite-clause-grammar-parsing-methods-and-non-terminals">Definite clause grammar parsing methods and non-terminals</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#predicate-properties">Predicate properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="#finding-declared-predicates">Finding declared predicates</a></li>
<li class="toctree-l3"><a class="reference internal" href="#calling-prolog-predicates">Calling Prolog predicates</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#calling-prolog-built-in-predicates">Calling Prolog built-in predicates</a></li>
<li class="toctree-l4"><a class="reference internal" href="#calling-prolog-non-standard-built-in-meta-predicates">Calling Prolog non-standard built-in meta-predicates</a></li>
<li class="toctree-l4"><a class="reference internal" href="#calling-prolog-foreign-predicates">Calling Prolog foreign predicates</a></li>
<li class="toctree-l4"><a class="reference internal" href="#calling-prolog-user-defined-plain-predicates">Calling Prolog user-defined plain predicates</a></li>
<li class="toctree-l4"><a class="reference internal" href="#calling-prolog-module-predicates">Calling Prolog module predicates</a></li>
<li class="toctree-l4"><a class="reference internal" href="#calling-prolog-module-meta-predicates">Calling Prolog module meta-predicates</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#defining-prolog-multifile-predicates">Defining Prolog multifile predicates</a></li>
<li class="toctree-l3"><a class="reference internal" href="#asserting-and-retracting-prolog-predicates">Asserting and retracting Prolog predicates</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="inheritance.html">Inheritance</a></li>
<li class="toctree-l2"><a class="reference internal" href="events.html">Event-driven programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="threads.html">Multi-threading programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="errors.html">Error handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="reflection.html">Reflection</a></li>
<li class="toctree-l2"><a class="reference internal" href="programming.html">Writing and running applications</a></li>
<li class="toctree-l2"><a class="reference internal" href="printing.html">Printing messages and asking questions</a></li>
<li class="toctree-l2"><a class="reference internal" href="expansion.html">Term and goal expansion</a></li>
<li class="toctree-l2"><a class="reference internal" href="documenting.html">Documenting</a></li>
<li class="toctree-l2"><a class="reference internal" href="debugging.html">Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance.html">Performance</a></li>
<li class="toctree-l2"><a class="reference internal" href="installing.html">Installing Logtalk</a></li>
<li class="toctree-l2"><a class="reference internal" href="migration.html">Prolog integration and migration</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../refman/index.html">Reference Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devtools/index.html">Developer Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../libraries/index.html">Libraries</a></li>
<li class="toctree-l1"><a class="reference internal" href="../ports/index.html">Ports</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributions/index.html">Contributions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../bibliography.html">Bibliography</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>

    <p class="caption"><span class="caption-text">External Contents</span></p>
    <ul>
    <li class="toctree-l1"><a class="reference internal" href="../../apis/index.html">APIs</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://logtalk.org">Logtalk website</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://github.com/LogtalkDotOrg/logtalk3">GitHub repo</a></li>
    </ul>
  
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">The Logtalk Handbook</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">User Manual</a></li>
      <li class="breadcrumb-item active">Predicates</li>
      <li class="wy-breadcrumbs-aside">
              <a href="https://github.com/LogtalkDotOrg/logtalk3/blob/master/docs/handbook/sources/userman/predicates.rst" class="fa fa-github"> Edit on GitHub</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="predicates">
<span id="predicates-predicates"></span><h1>Predicates<a class="headerlink" href="#predicates" title="Link to this heading"></a></h1>
<p>Predicate directives and clauses can be encapsulated inside objects and
categories. Protocols can only contain predicate directives. From the
point of view of a traditional imperative object-oriented language,
predicates allow both object state and object behavior to be represented.
Mutable object state can be represented using dynamic object predicates
but should only be used when strictly necessary, as it breaks declarative
semantics.</p>
<section id="reserved-predicate-names">
<span id="predicates-reserved"></span><h2>Reserved predicate names<a class="headerlink" href="#reserved-predicate-names" title="Link to this heading"></a></h2>
<p>For practical and performance reasons, some predicate names have a fixed
interpretation. These predicates are declared in the built-in protocols.
They are: <a class="reference internal" href="../refman/methods/goal_expansion_2.html#methods-goal-expansion-2"><span class="std std-ref">goal_expansion/2</span></a> and <a class="reference internal" href="../refman/methods/term_expansion_2.html#methods-term-expansion-2"><span class="std std-ref">term_expansion/2</span></a>,
declared in the <a class="reference external" href="../../apis/expanding_0.html#expanding-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">expanding</span></a> protocol;
<a class="reference internal" href="../refman/methods/before_3.html#methods-before-3"><span class="std std-ref">before/3</span></a> and <a class="reference internal" href="../refman/methods/after_3.html#methods-after-3"><span class="std std-ref">after/3</span></a>, declared in the
<a class="reference external" href="../../apis/monitoring_0.html#monitoring-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">monitoring</span></a> protocol; and
<a class="reference internal" href="../refman/methods/forward_1.html#methods-forward-1"><span class="std std-ref">forward/1</span></a>, declared in the
<a class="reference external" href="../../apis/forwarding_0.html#forwarding-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">forwarding</span></a> protocol.
By default, the compiler prints a warning when
a definition for one of these predicates is found but the reference to
the corresponding built-in protocol is missing.</p>
</section>
<section id="declaring-predicates">
<span id="predicates-declaring"></span><h2>Declaring predicates<a class="headerlink" href="#declaring-predicates" title="Link to this heading"></a></h2>
<p>Logtalk provides a clear distinction between <em>declaring a predicate</em> and
<em>defining a predicate</em> and thus clear <a class="reference internal" href="../glossary.html#term-closed-world-assumption"><span class="xref std std-term">closed-world assumption</span></a> semantics.
Messages or calls for declared but undefined predicates fail. Messages or
calls for unknown (i.e., non-declared) predicates throw an error. Note that
this is a fundamental requirement for supporting <a class="reference internal" href="protocols.html#protocols-protocols"><span class="std std-ref">protocols</span></a>:
we must be able to declare a predicate without necessarily defining it.</p>
<p>All object (or category) predicates that we want to access from other
objects (or categories) must be explicitly declared. A predicate
declaration must contain, at least, a <em>scope</em> directive. Other
directives may be used to document the predicate or to ensure proper
compilation of the predicate clauses.</p>
<section id="scope-directives">
<span id="predicates-scope"></span><h3>Scope directives<a class="headerlink" href="#scope-directives" title="Link to this heading"></a></h3>
<p>A predicate scope directive specifies <em>from where</em> the predicate can be
called, i.e. its <em>visibility</em>. Predicates can be <em>public</em>, <em>protected</em>,
<em>private</em>, or <em>local</em>. Public predicates can be called from any object.
Protected predicates can only be called from the container object or
from a container descendant. Private predicates can only be called from
the container object. Predicates are local when they are not declared in
a scope directive. Local predicates, like private predicates, can only be
called from the container object (or category), but they are <em>invisible</em>
to the reflection built-in methods (<a class="reference internal" href="../refman/methods/current_predicate_1.html#methods-current-predicate-1"><span class="std std-ref">current_predicate/1</span></a>
and <a class="reference internal" href="../refman/methods/predicate_property_2.html#methods-predicate-property-2"><span class="std std-ref">predicate_property/2</span></a>) and to the message error handling
mechanisms (i.e., sending a message corresponding to a local predicate
results in a <code class="docutils literal notranslate"><span class="pre">predicate_declaration</span></code> existence error instead of a scope
error).</p>
<p>The scope declarations are made using the directives
<a class="reference internal" href="../refman/directives/public_1.html#directives-public-1"><span class="std std-ref">public/1</span></a>, <a class="reference internal" href="../refman/directives/protected_1.html#directives-protected-1"><span class="std std-ref">protected/1</span></a>, and
<a class="reference internal" href="../refman/directives/private_1.html#directives-private-1"><span class="std std-ref">private/1</span></a>. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">public</span>(init<span class="o">/</span><span class="m">1</span>).

<span class="p">:- </span><span class="k">protected</span>(valid_init_option<span class="o">/</span><span class="m">1</span>).

<span class="p">:- </span><span class="k">private</span>(process_init_options<span class="o">/</span><span class="m">1</span>).
</pre></div>
</div>
<p>If a predicate does not have a (local or inherited) scope declaration,
it is assumed that the predicate is local. Note that we do not need to
write scope declarations for all defined predicates. One exception is
local dynamic predicates: declaring them as private predicates may allow
the Logtalk compiler to generate optimized code for asserting and
retracting clauses.</p>
<p>Note that a predicate scope directive doesn’t specify <em>where</em> a
predicate is, or can be, defined. For example, a private predicate can
only be called from an object holding its scope directive. But it can be
defined in descendant objects. A typical example is an object playing
the role of a class defining a private (possibly dynamic) predicate for
its descendant instances. Only the class can call (and possibly
assert/retract clauses for) the predicate, but its clauses can be
found/defined in the instances themselves.</p>
<p>Scope directives may also be used to declare grammar rule non-terminals
and operators. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">public</span>(url<span class="o">//</span><span class="m">1</span>).

<span class="p">:- </span><span class="k">public</span>(<span class="k">op</span>(<span class="m">800</span>, fx, tag)).
</pre></div>
</div>
<p>Note that, in the case of operators, the operator definitions don’t become
global when the entity containing the directives is compiled and loaded.
This prevents an application from breaking when, for example, an updated
third-party library adds new operators. It also allows loading entities
that provide conflicting operator definitions. Here the usual programming
idiom is to copy the operator definitions to a <code class="docutils literal notranslate"><span class="pre">uses/2</span></code> directive. For
example, the <a class="reference internal" href="../devtools/lgtunit.html"><span class="doc">lgtunit</span></a> tool makes available a <code class="docutils literal notranslate"><span class="pre">(=~=)/2</span></code>
predicate (for approximate float equality) that is intended to be used
as an infix operator:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">uses</span>(lgtunit, [
    <span class="k">op</span>(<span class="m">700</span>, xfx, <span class="o">=</span><span class="err">~</span><span class="o">=</span>), (<span class="o">=</span><span class="err">~</span><span class="o">=</span>)<span class="o">/</span><span class="m">2</span>
]).
</pre></div>
</div>
<p>Thus, in practice, the solution to use library entity operators in client
entities is the same for using library entity predicates with implicit
message-sending.</p>
</section>
<section id="mode-directive">
<span id="predicates-mode"></span><h3>Mode directive<a class="headerlink" href="#mode-directive" title="Link to this heading"></a></h3>
<p>Often predicates can only be called using specific argument patterns.
The valid arguments and instantiation modes of those arguments can be
documented using the <a class="reference internal" href="../refman/directives/mode_2.html#directives-mode-2"><span class="std std-ref">mode/2</span></a> directive. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">mode</span>(member(<span class="o">?</span>term, <span class="o">?</span>list), zero_or_more).
</pre></div>
</div>
<p id="predicates-mode-instantiation">The first directive argument describes a valid <em>calling mode</em>. The minimum
information will be the instantiation mode of each argument. The first
four possible values are described in the ISO Prolog Core standard <a class="reference internal" href="../bibliography.html#iso95" id="id1"><span>[ISO95]</span></a>
(but with the meaning of the <code class="docutils literal notranslate"><span class="pre">-</span></code> instantiation mode redefined here). The
remaining two can also be found in use in some Prolog systems.</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">+</span></code></dt><dd><p>Argument must be instantiated (but not necessarily ground).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">-</span></code></dt><dd><p>Argument should be a free (non-instantiated) variable. When bound,
the call will unify the computed term with the given argument.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">?</span></code></dt><dd><p>Argument can either be instantiated or free.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">&#64;</span></code></dt><dd><p>Argument will not be further instantiated (modified).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">++</span></code></dt><dd><p>Argument must be ground.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--</span></code></dt><dd><p>Argument must be unbound. Used mainly when returning an opaque term
(e.g., a stream handle).</p>
</dd>
</dl>
<p>Note that the <code class="docutils literal notranslate"><span class="pre">+</span></code> and <code class="docutils literal notranslate"><span class="pre">&#64;</span></code> instantiation modes have the same meaning
for atomic arguments. E.g. you can write either <code class="docutils literal notranslate"><span class="pre">+atom</span></code> or <code class="docutils literal notranslate"><span class="pre">&#64;atom</span></code>
but the first alternative is preferred.</p>
<p>The ISO <code class="docutils literal notranslate"><span class="pre">-</span></code> instantiation mode is equivalent to the Logtalk <code class="docutils literal notranslate"><span class="pre">--</span></code> mode,
allowing the use <code class="docutils literal notranslate"><span class="pre">-</span></code> to document predicates with output arguments that
don’t require those arguments to be unbound at call time and also accept
bound arguments without throwing an exception.</p>
<p>These six mode atoms are also declared as prefix operators by the
Logtalk compiler. This makes it possible to include type information
for each argument as in the example above. Some possible type
values are: <code class="docutils literal notranslate"><span class="pre">event</span></code>, <code class="docutils literal notranslate"><span class="pre">object</span></code>, <code class="docutils literal notranslate"><span class="pre">category</span></code>, <code class="docutils literal notranslate"><span class="pre">protocol</span></code>,
<code class="docutils literal notranslate"><span class="pre">callable</span></code>, <code class="docutils literal notranslate"><span class="pre">term</span></code>, <code class="docutils literal notranslate"><span class="pre">nonvar</span></code>, <code class="docutils literal notranslate"><span class="pre">var</span></code>, <code class="docutils literal notranslate"><span class="pre">atomic</span></code>, <code class="docutils literal notranslate"><span class="pre">atom</span></code>,
<code class="docutils literal notranslate"><span class="pre">number</span></code>, <code class="docutils literal notranslate"><span class="pre">integer</span></code>, <code class="docutils literal notranslate"><span class="pre">float</span></code>, <code class="docutils literal notranslate"><span class="pre">compound</span></code>, and <code class="docutils literal notranslate"><span class="pre">list</span></code>. The
first four are Logtalk specific. The remaining are common Prolog types.
We can also use our own types that can be either atoms or ground
compound terms. See the <a class="reference internal" href="../libraries/types.html#library-types"><span class="std std-ref">types</span></a> library documentation
for an extensive list of pre-defined types that cover most common use
cases.</p>
<p id="predicates-mode-number-of-proofs">The second directive argument documents the <em>number of proofs</em>, but not
necessarily distinct solutions, for the specified mode. As an example,
the <code class="docutils literal notranslate"><span class="pre">member(X,</span> <span class="pre">[1,1,1,1])</span></code> goal has only one distinct solution but four
proofs for that solution. Note that different modes for the same predicate
often have different determinism. The possible values are:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">zero</span></code></dt><dd><p>Predicate always fails (e.g., the <code class="docutils literal notranslate"><span class="pre">false/0</span></code> standard predicate).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">one</span></code></dt><dd><p>Predicate always succeeds once (e.g., the <code class="docutils literal notranslate"><span class="pre">flush_output/0</span></code> standard predicate).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">zero_or_one</span></code></dt><dd><p>Predicate either fails or succeeds (e.g., the <code class="docutils literal notranslate"><span class="pre">atom/1</span></code> standard predicate).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">zero_or_more</span></code></dt><dd><p>Predicate has zero or more proofs (e.g., the <code class="docutils literal notranslate"><span class="pre">current_predicate/1</span></code> standard predicate).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">one_or_more</span></code></dt><dd><p>Predicate has one or more proofs (e.g., the <code class="docutils literal notranslate"><span class="pre">repeat/0</span></code> standard predicate).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">zero_or_error</span></code></dt><dd><p>Predicate either fails or throws an error.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">one_or_error</span></code></dt><dd><p>Predicate either succeeds once or throws an error (e.g., the <code class="docutils literal notranslate"><span class="pre">open/3</span></code> standard predicate).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">zero_or_one_or_error</span></code></dt><dd><p>Predicate succeeds once or fails or throws an error (e.g., the <code class="docutils literal notranslate"><span class="pre">get_char/1</span></code> standard predicate).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">zero_or_more_or_error</span></code></dt><dd><p>Predicate may fail or succeed multiple times or throw an error (e.g., the <code class="docutils literal notranslate"><span class="pre">retract/1</span></code> standard predicate).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">one_or_more_or_error</span></code></dt><dd><p>Predicate may succeed one or more times or throw an error.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">error</span></code></dt><dd><p>Predicate will throw an error (e.g., the <code class="docutils literal notranslate"><span class="pre">type_error/2</span></code> built-in method).</p>
</dd>
</dl>
<p>The last six values support documenting that some call modes may throw an
error or will throw an error <strong>despite the call arguments complying with the
expected types and instantiation modes</strong>. As an example, consider the <code class="docutils literal notranslate"><span class="pre">open/3</span></code>
standard predicate:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">mode</span>(<span class="k">open</span>(<span class="o">@</span>source_sink, <span class="o">@</span>io_mode, <span class="o">--</span>stream), one_or_error).
</pre></div>
</div>
<p>In this case, the mode directive tells the user that a valid call can still
throw an error (there may be e.g. a permission error opening the specified
source or sink).</p>
<p>Notice that using the <code class="docutils literal notranslate"><span class="pre">zero</span></code>, <code class="docutils literal notranslate"><span class="pre">one</span></code>, <code class="docutils literal notranslate"><span class="pre">zero_or_one</span></code>, <code class="docutils literal notranslate"><span class="pre">zero_or_more</span></code>, or
<code class="docutils literal notranslate"><span class="pre">one_or_more</span></code> modes is not only for predicates that never throw an exception;
they can also be used for any predicate that doesn’t throw an exception when
the arguments are valid. For example, the <code class="docutils literal notranslate"><span class="pre">current_predicate/1</span></code> standard
predicate throws an exception if the argument is neither a variable nor a
predicate indicator, but it succeeds zero or more times when its argument is
valid:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">mode</span>(<span class="k">current_predicate</span>(<span class="o">?</span>predicate_indicator), zero_or_more).
</pre></div>
</div>
<p>Some predicates have more than one valid mode, thus implying several mode
directives. For example, to document the possible use modes of the standard
<code class="docutils literal notranslate"><span class="pre">atom_concat/3</span></code> predicate, we would write:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">mode</span>(<span class="k">atom_concat</span>(<span class="o">?</span>atom, <span class="o">?</span>atom, <span class="o">+</span>atom), one_or_more).
<span class="p">:- </span><span class="k">mode</span>(<span class="k">atom_concat</span>(<span class="o">+</span>atom, <span class="o">+</span>atom, <span class="o">-</span>atom), one).
</pre></div>
</div>
<p>The first <code class="docutils literal notranslate"><span class="pre">mode/2</span></code> directive specifies that the <code class="docutils literal notranslate"><span class="pre">atom_concat/3</span></code> predicate
can be used to split an atom into a prefix and a suffix. The second <code class="docutils literal notranslate"><span class="pre">mode/2</span></code>
directive specifies that concatenating two atoms results in a new atom. There
are often several alternative <code class="docutils literal notranslate"><span class="pre">mode/2</span></code> directives that can be used to
specify a predicate. For example, an alternative to the second <code class="docutils literal notranslate"><span class="pre">mode/2</span></code>
directive above would be:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">mode</span>(<span class="k">atom_concat</span>(<span class="o">+</span>atom, <span class="o">+</span>atom, <span class="o">?</span>atom), zero_or_one).
</pre></div>
</div>
<p>In this case, the same information is provided by both alternatives. But the
first alternative is simpler and thus preferred.</p>
<p>Some old Prolog compilers supported some sort of mode directives to improve
performance. To the best of my knowledge, there is no modern Prolog compiler
supporting this kind of directive for that purpose. The current Logtalk version
simply parses this directive for collecting its information for use in the
<a class="reference internal" href="reflection.html#reflection-reflection"><span class="std std-ref">reflection API</span></a> (assuming the
<a class="reference internal" href="programming.html#flag-source-data"><span class="std std-ref">source_data</span></a> flag is turned on). In any case, the use
of mode directives is a good starting point for documenting your predicates.</p>
</section>
<section id="meta-predicate-directive">
<span id="predicates-meta"></span><h3>Meta-predicate directive<a class="headerlink" href="#meta-predicate-directive" title="Link to this heading"></a></h3>
<p>Some predicates may have arguments that will be called as goals, interpreted
as <a class="reference internal" href="../glossary.html#term-closure"><span class="xref std std-term">closures</span></a> that will be used for constructing goals, or
passing meta-arguments to calls to other meta-predicates. To ensure that these
goals will be executed in the correct context
(i.e., in the <a class="reference internal" href="../glossary.html#term-predicate-calling-context"><span class="xref std std-term">calling context</span></a>, not in the
meta-predicate <a class="reference internal" href="../glossary.html#term-predicate-definition-context"><span class="xref std std-term">definition context</span></a>), we
need to use the <a class="reference internal" href="../refman/directives/meta_predicate_1.html#directives-meta-predicate-1"><span class="std std-ref">meta_predicate/1</span></a> directive (in the case of
<em>meta non-terminals</em>, there’s also a <a class="reference internal" href="../refman/directives/meta_non_terminal_1.html#directives-meta-non-terminal-1"><span class="std std-ref">meta_non_terminal/1</span></a>
directive). For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">meta_predicate</span>(<span class="k">findall</span>(<span class="o">*</span>, <span class="m">0</span>, <span class="o">*</span>)).
<span class="p">:- </span><span class="k">meta_predicate</span>(map(<span class="m">2</span>, <span class="o">*</span>, <span class="o">*</span>)).
</pre></div>
</div>
<p>The meta-predicate mode arguments in this directive have the following
meaning:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">0</span></code></dt><dd><p>Meta-argument that will be called as a goal.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">N</span></code></dt><dd><p>Meta-argument that will be a closure used to construct a call by
extending it with <code class="docutils literal notranslate"><span class="pre">N</span></code> arguments. The value of <code class="docutils literal notranslate"><span class="pre">N</span></code> must be a
positive integer.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">::</span></code></dt><dd><p>Argument that is context-aware but that will not be called as a goal
or a closure. It can contain, however, sub-terms that will be called
as goals or closures.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">^</span></code></dt><dd><p>Goal that may be existentially quantified (<code class="docutils literal notranslate"><span class="pre">Vars^Goal</span></code>).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">*</span></code></dt><dd><p>Normal argument.</p>
</dd>
</dl>
<p>The following meta-predicate mode arguments are for use only when writing
backend Prolog <a class="reference internal" href="../glossary.html#term-adapter-file"><span class="xref std std-term">adapter files</span></a> to deal with proprietary
built-in meta-predicates and meta-directives:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">/</span></code></dt><dd><p>Predicate indicator (<code class="docutils literal notranslate"><span class="pre">Name/Arity</span></code>), list of predicate indicators,
or conjunction of predicate indicators.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">//</span></code></dt><dd><p>Non-terminal indicator (<code class="docutils literal notranslate"><span class="pre">Name//Arity</span></code>), list of predicate
indicators, or conjunction of predicate indicators.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">[0]</span></code></dt><dd><p>List of goals.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">[N]</span></code></dt><dd><p>List of closures.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">[/]</span></code></dt><dd><p>List of predicate indicators.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">[//]</span></code></dt><dd><p>List of non-terminal indicators.</p>
</dd>
</dl>
<p>To the best of my knowledge, the use of non-negative integers to specify
closures was first introduced on Quintus Prolog for providing information
for predicate cross-reference tools.</p>
<p>Note that Logtalk meta-predicate semantics are different from Prolog
meta-predicate semantics (assuming a predicate-based module system as
common):</p>
<ul class="simple">
<li><p>Meta-arguments are always called in the meta-predicate calling context,
independent of using explicit or implicit message-sending (to the object
defining the meta-predicate when not local). Most Prolog systems have
different semantics for explicit versus implicit module qualification.</p></li>
<li><p>Logtalk is not based on a predicate prefixing mechanism. Therefore, the
meta-predicate directive is required for any predicate with meta-arguments
(including when simply passing the meta-arguments to a call to another
meta-predicate). This is usually not required in Prolog systems due to the
module prefixing of meta-arguments.</p></li>
<li><p>Sending a message from a meta-predicate definition to call a meta-predicate
defined in another object resets the calling context for any passed
meta-argument to the object sending the message (including for messages to
<em>self</em>). Meta-arguments behave differently in Prolog systems due to their
module prefixing.</p></li>
<li><p>Logtalk protects from common scenarios where specially crafted meta-predicate
definitions are used to break object (and category) encapsulation by changing
the meta-arguments passed by client code or trying to subvert the implicit
calling context to call client predicates other than the predicates passed as
meta-arguments.</p></li>
</ul>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>As each Logtalk entity is independently compiled, this directive must
be included in every object or category that contains a definition for
the described meta-predicate, even if the meta-predicate declaration
is inherited from another entity, to ensure proper compilation of
meta-arguments.</p>
</div>
</section>
<section id="discontiguous-directive">
<span id="predicates-discontiguous"></span><h3>Discontiguous directive<a class="headerlink" href="#discontiguous-directive" title="Link to this heading"></a></h3>
<p>The clause of an object (or category) predicate may not be contiguous.
In that case, we must declare the predicate discontiguous by using the
<a class="reference internal" href="../refman/directives/discontiguous_1.html#directives-discontiguous-1"><span class="std std-ref">discontiguous/1</span></a> directive:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">discontiguous</span>(foo<span class="o">/</span><span class="m">1</span>).
</pre></div>
</div>
<p>This is a directive that we should avoid using: it makes your code
harder to read, and it is not supported by some Prolog backends.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>As each Logtalk entity is compiled independently of other entities,
this directive must be included in every object or category that
contains a definition for the described predicate (even if the
predicate declaration is inherited from another entity).</p>
</div>
</section>
<section id="dynamic-directive">
<span id="predicates-dynamic"></span><h3>Dynamic directive<a class="headerlink" href="#dynamic-directive" title="Link to this heading"></a></h3>
<p>An object predicate can be static or dynamic. By default, all predicates (and
non-terminals) of static objects defined in source files are static. To declare
a dynamic predicate (or non-terminal), we use the <a class="reference internal" href="../refman/directives/dynamic_1.html#directives-dynamic-1"><span class="std std-ref">dynamic/1</span></a>
directive. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">dynamic</span>(foo<span class="o">/</span><span class="m">1</span>).
</pre></div>
</div>
<p>Predicates of objects dynamically created at runtime (using the
<a class="reference internal" href="../refman/predicates/create_object_4.html#predicates-create-object-4"><span class="std std-ref">create_object/4</span></a> built-in predicate) and predicates of
dynamic objects defined in source files (using the <a class="reference internal" href="../refman/directives/dynamic_0.html#directives-dynamic-0"><span class="std std-ref">dynamic/0</span></a>
directive) are implicitly dynamic.</p>
<p>Dynamic predicates can be used to represent persistent mutable object state.
Note that static objects may declare and define dynamic predicates. Categories
can only declare dynamic predicates (with the importing objects holding the
predicate definitions).</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>As each Logtalk entity is compiled independently from other entities, this
directive must be included in every object that contains a definition for
the described predicate (even if the predicate declaration is inherited
from another object or imported from a category). If we omit the dynamic
declaration then the predicate definition will be compiled static.</p>
</div>
</section>
<section id="operator-directive">
<span id="predicates-op"></span><h3>Operator directive<a class="headerlink" href="#operator-directive" title="Link to this heading"></a></h3>
<p>An object (or category) predicate can be declared as an operator using
the familiar <a class="reference internal" href="../refman/directives/op_3.html#directives-op-3"><span class="std std-ref">op/3</span></a> directive:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">op</span>(<span class="nv">Priority</span>, <span class="nv">Specifier</span>, <span class="nv">Operator</span>).
</pre></div>
</div>
<p>Operators are local to the object (or category) where they are declared.
This means that, if you declare a public predicate as an operator, you
cannot use operator notation when sending to an object (where the
predicate is visible) the respective message (as this would imply
visibility of the operator declaration in the context of the <em>sender</em> of
the message). If you want to declare global operators and, at the same
time, use them inside an entity, just write the corresponding directives
at the top of your source file, before the entity opening directive.</p>
<p>Note that operators can also be declared using a scope directive. Only
these operators are visible to the <a class="reference internal" href="../refman/methods/current_op_3.html#methods-current-op-3"><span class="std std-ref">current_op/3</span></a> reflection
method.</p>
<p>When the same operators are used on several entities within the same source
file, the corresponding directives must either be repeated in each entity or
appear before any entity that uses them. But in the later case, this results
in a global scope for the operators. If you prefer the operators to be local
to the source file, just <em>undefine</em> them at the end of the file. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="c">% before any entity that uses the operator</span>
<span class="p">:- </span><span class="k">op</span>(<span class="m">400</span>, xfx, results).

...

<span class="c">% after all entities that used the operator</span>
<span class="p">:- </span><span class="k">op</span>(<span class="m">0</span>, xfx, results).
</pre></div>
</div>
<p>Global operators can be declared in the application loader file.</p>
</section>
<section id="uses-directive">
<span id="predicates-uses"></span><h3>Uses directive<a class="headerlink" href="#uses-directive" title="Link to this heading"></a></h3>
<p>When a predicate makes heavy use of predicates defined on other objects,
its predicate clauses can be verbose due to all the necessary
message-sending goals. Consider the following example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>foo <span class="o">:-</span>
    ...,
    <span class="k">findall</span>(<span class="nv">X</span>, list<span class="o">::</span>member(<span class="nv">X</span>, <span class="nv">L</span>), <span class="nv">A</span>),
    list<span class="o">::</span>append(<span class="nv">A</span>, <span class="nv">B</span>, <span class="nv">C</span>),
    list<span class="o">::</span>select(<span class="nv">Y</span>, <span class="nv">C</span>, <span class="nv">R</span>),
    ...
</pre></div>
</div>
<p>Logtalk provides a directive, <a class="reference internal" href="../refman/directives/uses_2.html#directives-uses-2"><span class="std std-ref">uses/2</span></a>, which allows us to
simplify the code above. One of the usage templates for this directive is:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">uses</span>(<span class="nv">Object</span>, [
    <span class="nv">Name1</span><span class="o">/</span><span class="nv">Arity1</span>, <span class="nv">Name2</span><span class="o">/</span><span class="nv">Arity2</span>, ...
]).
</pre></div>
</div>
<p>Rewriting the code above using this directive results in a simplified
and more readable predicate definition:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">uses</span>(list, [
    append<span class="o">/</span><span class="m">3</span>, member<span class="o">/</span><span class="m">2</span>, select<span class="o">/</span><span class="m">3</span>
]).

foo <span class="o">:-</span>
    ...,
    <span class="k">findall</span>(<span class="nv">X</span>, member(<span class="nv">X</span>, <span class="nv">L</span>), <span class="nv">A</span>),
    append(<span class="nv">A</span>, <span class="nv">B</span>, <span class="nv">C</span>),
    select(<span class="nv">Y</span>, <span class="nv">C</span>, <span class="nv">R</span>),
    ...
</pre></div>
</div>
<p>Logtalk also supports an extended version of this directive that allows
the declaration of <a class="reference internal" href="../glossary.html#term-predicate-alias"><span class="xref std std-term">predicate aliases</span></a> using the
notation <code class="docutils literal notranslate"><span class="pre">Predicate</span> <span class="pre">as</span> <span class="pre">Alias</span></code> (or the alternative notation
<code class="docutils literal notranslate"><span class="pre">Predicate::Alias</span></code>). For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">uses</span>(btrees, [new<span class="o">/</span><span class="m">1</span> <span class="o">as</span> new_btree<span class="o">/</span><span class="m">1</span>]).
<span class="p">:- </span><span class="k">uses</span>(queues, [new<span class="o">/</span><span class="m">1</span> <span class="o">as</span> new_queue<span class="o">/</span><span class="m">1</span>]).
</pre></div>
</div>
<p>You may use this extended version for solving conflicts between predicates
declared on several <code class="docutils literal notranslate"><span class="pre">uses/2</span></code> directives or just for giving new names to
the predicates that will be more meaningful on their using context.</p>
<p>Predicate aliases can also be used to define
<a class="reference internal" href="../glossary.html#term-predicate-shorthand"><span class="xref std std-term">predicate shorthands</span></a>, simplifying code
maintenance. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">uses</span>(pretty_printer, [
    indent(<span class="m">4</span>, <span class="nv">Term</span>) <span class="o">as</span> indent(<span class="nv">Term</span>)
]).
</pre></div>
</div>
<p>Assuming multiple calls to the shorthand, a change to the indent value
will require a change to a single line instead of changing every call.</p>
<p>Another common use of predicate aliases is changing the order of the
predicate arguments without using <a class="reference internal" href="#predicates-lambdas"><span class="std std-ref">lambda expressions</span></a>.
For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">uses</span>(meta, [
    fold_left(<span class="nv">Closure</span>, <span class="nv">Result0</span>, <span class="nv">List</span>, <span class="nv">Result</span>) <span class="o">as</span> foldl(<span class="nv">Closure</span>, <span class="nv">List</span>, <span class="nv">Result0</span>, <span class="nv">Result</span>)
]).
</pre></div>
</div>
<p>See the directive documentation for details and other examples.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">uses/2</span></code> directive allows simpler predicate definitions as long as
there are no conflicts between the predicates declared in the directive
and the predicates defined in the object (or category) containing the
directive. A predicate (or its alias if defined) cannot be listed in
more than one <code class="docutils literal notranslate"><span class="pre">uses/2</span></code> directive. In addition, a <code class="docutils literal notranslate"><span class="pre">uses/2</span></code> directive
cannot list a predicate (or its alias if defined) that is defined in
the object (or category) containing the directive. Any conflicts are
reported by Logtalk as compilation errors.</p>
<p>The object identifier argument can also be a <a class="reference internal" href="../glossary.html#term-parameter-variable"><span class="xref std std-term">parameter variable</span></a>
when using the directive in a parametric object or a parametric category.
In this case, <a class="reference internal" href="../glossary.html#term-dynamic-binding"><span class="xref std std-term">dynamic binding</span></a> will necessarily be used for all listed
predicates (and non-terminals). The parameter variable must be instantiated
at runtime when the messages are sent. This feature simplifies experimenting
with multiple implementations of the same protocol (for example, to evaluate
the performance of each implementation for a particular case). It also
simplifies writing tests that check multiple implementations of the same
protocol.</p>
<p>An object (or category) can make a predicate listed in a <code class="docutils literal notranslate"><span class="pre">uses/2</span></code> (or
<code class="docutils literal notranslate"><span class="pre">use_module/2</span></code>) directive part of its protocol by simply adding a scope
directive for the predicate. For example, in the <code class="docutils literal notranslate"><span class="pre">statistics</span></code> library
we have:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">public</span>(modes<span class="o">/</span><span class="m">2</span>).
<span class="p">:- </span><span class="k">uses</span>(numberlist, [modes<span class="o">/</span><span class="m">2</span>]).
</pre></div>
</div>
<p>Therefore, a goal such as <code class="docutils literal notranslate"><span class="pre">sample::modes(Sample,</span> <span class="pre">Modes)</span></code> implicitly calls
<code class="docutils literal notranslate"><span class="pre">numberlist::modes(Sample,</span> <span class="pre">Modes)</span></code> without requiring an explicit local
definition for the <code class="docutils literal notranslate"><span class="pre">modes/2</span></code> predicate (which would trigger a compilation
error).</p>
</section>
<section id="alias-directive">
<span id="predicates-alias"></span><h3>Alias directive<a class="headerlink" href="#alias-directive" title="Link to this heading"></a></h3>
<p>Logtalk allows the definition of an alternative name for an inherited or
imported predicate (or for an inherited or imported grammar rule
non-terminal) through the use of the <a class="reference internal" href="../refman/directives/alias_2.html#directives-alias-2"><span class="std std-ref">alias/2</span></a> directive:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">alias</span>(<span class="nv">Entity</span>, [
    <span class="nv">Predicate1</span> <span class="o">as</span> <span class="nv">Alias1</span>,
    <span class="nv">Predicate2</span> <span class="o">as</span> <span class="nv">Alias2</span>,
    ...
]).
</pre></div>
</div>
<p>This directive can be used in objects, protocols, or categories. The
first argument, <code class="docutils literal notranslate"><span class="pre">Entity</span></code>, must be an entity referenced in the opening
directive of the entity containing the <code class="docutils literal notranslate"><span class="pre">alias/2</span></code> directive. It can be
an extended or implemented protocol, an imported category, an extended
prototype, an instantiated class, or a specialized class. The second
argument is a list of pairs of predicate indicators (or grammar rule
non-terminal indicators) using the <code class="docutils literal notranslate"><span class="pre">as</span></code> infix operator.</p>
<p>A common use for the <code class="docutils literal notranslate"><span class="pre">alias/2</span></code> directive is to give an alternative
name to an inherited predicate in order to improve readability. For
example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(square,
    <span class="k">extends</span>(rectangle)).

<span class="p">    :- </span><span class="k">alias</span>(rectangle, [width<span class="o">/</span><span class="m">1</span> <span class="o">as</span> side<span class="o">/</span><span class="m">1</span>]).

    ...

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>The directive allows both <code class="docutils literal notranslate"><span class="pre">width/1</span></code> and <code class="docutils literal notranslate"><span class="pre">side/1</span></code> to be used as
messages to the object <code class="docutils literal notranslate"><span class="pre">square</span></code>. Thus, using this directive, there is
no need to explicitly declare and define a “new” <code class="docutils literal notranslate"><span class="pre">side/1</span></code> predicate.
Note that the <code class="docutils literal notranslate"><span class="pre">alias/2</span></code> directive does not rename a predicate, it only
provides an alternative, additional name; the original name continues to
be available (although it may be masked due to the default inheritance
conflict mechanism).</p>
<p>Another common use for this directive is to solve conflicts when two
inherited predicates have the same name and arity. We may want to
call the predicate that is masked out by the Logtalk lookup algorithm
(see the <a class="reference internal" href="inheritance.html#inheritance-inheritance"><span class="std std-ref">Inheritance</span></a> section) or we may need to
call both predicates. This is simply accomplished by using the
<code class="docutils literal notranslate"><span class="pre">alias/2</span></code> directive to give alternative names to masked-out or
conflicting predicates. Consider the following example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(my_data_structure,
    <span class="k">extends</span>(list, set)).

<span class="p">    :- </span><span class="k">alias</span>(list, [member<span class="o">/</span><span class="m">2</span> <span class="o">as</span> list_member<span class="o">/</span><span class="m">2</span>]).
<span class="p">    :- </span><span class="k">alias</span>(set,  [member<span class="o">/</span><span class="m">2</span> <span class="o">as</span> set_member<span class="o">/</span><span class="m">2</span>]).

    ...

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Assuming that both <code class="docutils literal notranslate"><span class="pre">list</span></code> and <code class="docutils literal notranslate"><span class="pre">set</span></code> objects define a <code class="docutils literal notranslate"><span class="pre">member/2</span></code>
predicate, without the <code class="docutils literal notranslate"><span class="pre">alias/2</span></code> directives, only the definition of
<code class="docutils literal notranslate"><span class="pre">member/2</span></code> predicate in the object <code class="docutils literal notranslate"><span class="pre">list</span></code> would be visible on the
object <code class="docutils literal notranslate"><span class="pre">my_data_structure</span></code>, as a result of the application of the
Logtalk predicate lookup algorithm. By using the <code class="docutils literal notranslate"><span class="pre">alias/2</span></code> directives,
all the following messages would be valid (assuming a public scope for
the predicates):</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>% uses list member/2
| ?- my_data_structure::list_member(X, L).

% uses set member/2
| ?- my_data_structure::set_member(X, L).

% uses list member/2
| ?- my_data_structure::member(X, L).
</pre></div>
</div>
<p>When used this way, the <code class="docutils literal notranslate"><span class="pre">alias/2</span></code> directive provides functionality
similar to programming constructs of other object-oriented languages
that support multi-inheritance (the most notable example probably being
the renaming of inherited features in Eiffel).</p>
<p>Note that the <code class="docutils literal notranslate"><span class="pre">alias/2</span></code> directive never hides a predicate that is
visible on the entity containing the directive as a result of the
Logtalk lookup algorithm. However, it may be used to make visible a
predicate that otherwise would be masked by another predicate, as
illustrated in the above example.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">alias/2</span></code> directive may also be used to give access to an
inherited predicate, which otherwise would be masked by another
inherited predicate, while keeping the original name as follows:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(my_data_structure,
    <span class="k">extends</span>(list, set)).

<span class="p">    :- </span><span class="k">alias</span>(list, [member<span class="o">/</span><span class="m">2</span> <span class="o">as</span> list_member<span class="o">/</span><span class="m">2</span>]).
<span class="p">    :- </span><span class="k">alias</span>(set,  [member<span class="o">/</span><span class="m">2</span> <span class="o">as</span> set_member<span class="o">/</span><span class="m">2</span>]).

    member(<span class="nv">X</span>, <span class="nv">L</span>) <span class="o">:-</span>
        <span class="o">^^</span>set_member(<span class="nv">X</span>, <span class="nv">L</span>).

    ...

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Thus, when sending the message <code class="docutils literal notranslate"><span class="pre">member/2</span></code> to <code class="docutils literal notranslate"><span class="pre">my_data_structure</span></code>,
the predicate definition in <code class="docutils literal notranslate"><span class="pre">set</span></code> will be used instead of the one
contained in <code class="docutils literal notranslate"><span class="pre">list</span></code>.</p>
</section>
<section id="documenting-directive">
<span id="predicates-info"></span><h3>Documenting directive<a class="headerlink" href="#documenting-directive" title="Link to this heading"></a></h3>
<p>A predicate can be documented with arbitrary user-defined information by
using the <a class="reference internal" href="../refman/directives/info_2.html#directives-info-2"><span class="std std-ref">info/2</span></a> directive:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">info</span>(<span class="nv">Name</span><span class="o">/</span><span class="nv">Arity</span>, <span class="nv">List</span>).
</pre></div>
</div>
<p>The second argument is a list of <code class="docutils literal notranslate"><span class="pre">Key</span> <span class="pre">is</span> <span class="pre">Value</span></code> terms. See the
<a class="reference internal" href="documenting.html#documenting-documenting"><span class="std std-ref">Documenting</span></a> section for details.</p>
</section>
<section id="multifile-directive">
<span id="predicates-multifile"></span><h3>Multifile directive<a class="headerlink" href="#multifile-directive" title="Link to this heading"></a></h3>
<p>A predicate can be declared <a class="reference internal" href="../glossary.html#term-multifile-predicate"><span class="xref std std-term">multifile</span></a> by using
the <a class="reference internal" href="../refman/directives/multifile_1.html#directives-multifile-1"><span class="std std-ref">multifile/1</span></a> directive:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">multifile</span>(<span class="nv">Name</span><span class="o">/</span><span class="nv">Arity</span>).
</pre></div>
</div>
<p>This allows clauses for a predicate to be defined in several objects
and/or categories. This is a directive that should be used with care.
It’s commonly used in the definition of <a class="reference internal" href="../glossary.html#term-hook-predicate"><span class="xref std std-term">hook predicates</span></a>.
Multifile predicates (and non-terminals) may also be declared dynamic
using the same predicate (or non-terminal) notation (multifile predicates
are static by default).</p>
<p>Logtalk precludes using a multifile predicate for breaking object
encapsulation by checking that the object (or category) declaring the
predicate (using a scope directive) defines it also as multifile.
This entity is said to contain the <em>primary declaration</em> for the multifile
predicate. Entities containing primary multifile predicate declarations
must always be compiled before entities defining clauses for those multifile
predicates. The Logtalk compiler will print a warning if the scope
directive is missing. Note also that the <code class="docutils literal notranslate"><span class="pre">multifile/1</span></code> directive
is mandatory when defining multifile predicates.</p>
<p>Consider the following simple example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(main).

<span class="p">    :- </span><span class="k">public</span>(a<span class="o">/</span><span class="m">1</span>).
<span class="p">    :- </span><span class="k">multifile</span>(a<span class="o">/</span><span class="m">1</span>).
    a(<span class="m">1</span>).

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>After compiling and loading the <code class="docutils literal notranslate"><span class="pre">main</span></code> object, we can define other
objects (or categories) that contribute with clauses for the multifile
predicate. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(other).

<span class="p">    :- </span><span class="k">multifile</span>(main<span class="o">::</span>a<span class="o">/</span><span class="m">1</span>).
    main<span class="o">::</span>a(<span class="m">2</span>).
    main<span class="o">::</span>a(<span class="nv">X</span>) <span class="o">:-</span>
        b(<span class="nv">X</span>).

    b(<span class="m">3</span>).
    b(<span class="m">4</span>).

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>After compiling and loading the above objects, you can use queries such
as:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- main::a(X).

X = 1 ;
X = 2 ;
X = 3 ;
X = 4
yes
</pre></div>
</div>
<p>Note that the order of multifile predicate clauses depends on several factors,
including loading order and compiler implementation details. Therefore, your
code should never assume or rely on a specific order of the multifile predicate
clauses.</p>
<p>When a clause of a multifile predicate is a rule, its body is compiled
within the context of the object or category defining the clause. This
allows clauses for multifile predicates to call local object or category
predicates. But the values of the <em>sender</em>, <em>this</em>, and <em>self</em> in the
implicit execution context are passed from the clause head to the clause
body. This is necessary to ensure that these values are always valid and
to allow multifile predicate clauses to be defined in categories. A call
to the <code class="docutils literal notranslate"><span class="pre">parameter/2</span></code> execution context methods, however, retrieves
parameters of the entity defining the clause, not from the entity for
which the clause is defined. The parameters of the entity for which the
clause is defined can be accessed by simple unification at the clause
head.</p>
<p>Multifile predicate rules should not contain cuts, as these may prevent
other clauses for the predicate from being used by callers. The compiler
prints by default a warning when a cut is found in a multifile predicate
definition.</p>
<p>Local calls to the database methods from multifile predicate clauses
defined in an object take place in the object’s own database instead of
the database of the entity holding the multifile predicate primary
declaration. Similarly, local calls to the <code class="docutils literal notranslate"><span class="pre">expand_term/2</span></code> and
<code class="docutils literal notranslate"><span class="pre">expand_goal/2</span></code> methods from a multifile predicate clause look for
clauses of the <code class="docutils literal notranslate"><span class="pre">term_expansion/2</span></code> and <code class="docutils literal notranslate"><span class="pre">goal_expansion/2</span></code> hook
predicates starting from the entity defining the clause instead of the
entity holding the multifile predicate primary declaration. Local calls
to the <code class="docutils literal notranslate"><span class="pre">current_predicate/1</span></code>, <code class="docutils literal notranslate"><span class="pre">predicate_property/2</span></code>, and
<code class="docutils literal notranslate"><span class="pre">current_op/3</span></code> methods from multifile predicate clauses defined in an
object also lookup predicates and their properties in the object’s own
database instead of the database of the entity holding the multifile
predicate primary declaration.</p>
</section>
<section id="coinductive-directive">
<span id="predicates-coinductive"></span><h3>Coinductive directive<a class="headerlink" href="#coinductive-directive" title="Link to this heading"></a></h3>
<p>A predicate can be declared <a class="reference internal" href="../glossary.html#term-coinductive-predicate"><span class="xref std std-term">coinductive</span></a> by
using the <a class="reference internal" href="../refman/directives/coinductive_1.html#directives-coinductive-1"><span class="std std-ref">coinductive/1</span></a> directive. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">coinductive</span>(comember<span class="o">/</span><span class="m">2</span>).
</pre></div>
</div>
<p>Logtalk support for coinductive predicates is experimental and requires a
<a class="reference internal" href="../glossary.html#term-backend-Prolog-compiler"><span class="xref std std-term">backend Prolog compiler</span></a> with minimal support for cyclic terms. The
value of the read-only <a class="reference internal" href="programming.html#flag-coinduction"><span class="std std-ref">coinduction flag</span></a> is set to
<code class="docutils literal notranslate"><span class="pre">supported</span></code> for the backend Prolog compilers providing that support.</p>
</section>
<section id="synchronized-directive">
<span id="predicates-synchronized"></span><h3>Synchronized directive<a class="headerlink" href="#synchronized-directive" title="Link to this heading"></a></h3>
<p>A predicate can be declared <a class="reference internal" href="../glossary.html#term-synchronized-predicate"><span class="xref std std-term">synchronized</span></a> by
using the <a class="reference internal" href="../refman/directives/synchronized_1.html#directives-synchronized-1"><span class="std std-ref">synchronized/1</span></a> directive. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">synchronized</span>(write_log_entry<span class="o">/</span><span class="m">2</span>).
<span class="p">:- </span><span class="k">synchronized</span>([produce<span class="o">/</span><span class="m">1</span>, consume<span class="o">/</span><span class="m">1</span>]).
</pre></div>
</div>
<p>See the section on
<a class="reference internal" href="threads.html#threads-synchronized-predicates"><span class="std std-ref">synchronized predicates</span></a>
for details.</p>
</section>
</section>
<section id="defining-predicates">
<span id="predicates-defining"></span><h2>Defining predicates<a class="headerlink" href="#defining-predicates" title="Link to this heading"></a></h2>
<section id="object-predicates">
<span id="predicates-objects"></span><h3>Object predicates<a class="headerlink" href="#object-predicates" title="Link to this heading"></a></h3>
<p>We define object predicates as we have always defined Prolog predicates,
the only difference being that we have four more control structures (the
three message-sending operators plus the external call operator) to play
with. For example, if we wish to define an object containing common
utility list predicates like <code class="docutils literal notranslate"><span class="pre">append/2</span></code> or <code class="docutils literal notranslate"><span class="pre">member/2</span></code> we could write
something like:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(list).

<span class="p">    :- </span><span class="k">public</span>(append<span class="o">/</span><span class="m">3</span>).
    append([], <span class="nv">L</span>, <span class="nv">L</span>).
    append([<span class="nv">H</span>| <span class="nv">T</span>], <span class="nv">L</span>, [<span class="nv">H</span>| <span class="nv">T2</span>]) <span class="o">:-</span>
        append(<span class="nv">T</span>, <span class="nv">L</span>, <span class="nv">T2</span>).

<span class="p">    :- </span><span class="k">public</span>(member<span class="o">/</span><span class="m">2</span>).
    member(<span class="nv">H</span>, [<span class="nv">H</span>| <span class="nv">_</span>]).
    member(<span class="nv">H</span>, [<span class="nv">_</span>| <span class="nv">T</span>]) <span class="o">:-</span>
        member(<span class="nv">H</span>, <span class="nv">T</span>).

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Note that, abstracting from the opening and closing object directives
and the scope directives, what we have written is also valid Prolog code.
Calls in a predicate definition body default to the local predicates
unless we use the message-sending operators or the external call operator.
This simplifies conversion from plain Prolog code to Logtalk objects:
often we just need to add the necessary encapsulation and scope directives
to the old code.</p>
</section>
<section id="category-predicates">
<span id="predicates-categories"></span><h3>Category predicates<a class="headerlink" href="#category-predicates" title="Link to this heading"></a></h3>
<p>A category can only contain clauses for static predicates. But there are
no restrictions in declaring and calling dynamic predicates from inside
a category. Because a category can be imported by multiple objects, dynamic
predicates must be called either in the context of <a class="reference internal" href="../glossary.html#term-self"><span class="xref std std-term">self</span></a>, using the
<a class="reference internal" href="../glossary.html#term-message-to-self"><span class="xref std std-term">message to self</span></a> control structure, <a class="reference internal" href="../refman/control/send_to_self_1.html#control-send-to-self-1"><span class="std std-ref">(::)/1</span></a>, or
in the context of <a class="reference internal" href="../glossary.html#term-this"><span class="xref std std-term">this</span></a> (i.e., in the context of the object importing
the category). For example, if we want to define a category implementing
attributes using the dynamic database of <em>self</em> we could write:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">category</span>(attributes).

<span class="p">    :- </span><span class="k">public</span>(get<span class="o">/</span><span class="m">2</span>).
<span class="p">    :- </span><span class="k">public</span>(set<span class="o">/</span><span class="m">2</span>).

<span class="p">    :- </span><span class="k">private</span>(attribute_<span class="o">/</span><span class="m">2</span>).
<span class="p">    :- </span><span class="k">dynamic</span>(attribute_<span class="o">/</span><span class="m">2</span>).

    get(<span class="nv">Var</span>, <span class="nv">Value</span>) <span class="o">:-</span>
        <span class="o">::</span>attribute_(<span class="nv">Var</span>, <span class="nv">Value</span>).

    set(<span class="nv">Var</span>, <span class="nv">Value</span>) <span class="o">:-</span>
        <span class="o">::</span><span class="k">retractall</span>(attribute_(<span class="nv">Var</span>, <span class="nv">_</span>)),
        <span class="o">::</span><span class="k">asserta</span>(attribute_(<span class="nv">Var</span>, <span class="nv">Value</span>).

<span class="p">:- </span><span class="k">end_category</span>.
</pre></div>
</div>
<p>In this case, the <code class="docutils literal notranslate"><span class="pre">get/2</span></code> and <code class="docutils literal notranslate"><span class="pre">set/2</span></code> predicates will always
access/update the correct definition, contained in the object receiving
the messages.</p>
<p>In alternative, if we want a category implementing attributes using the
dynamic database of <em>this</em>, we would write instead:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">category</span>(attributes).

<span class="p">    :- </span><span class="k">public</span>(get<span class="o">/</span><span class="m">2</span>).
<span class="p">    :- </span><span class="k">public</span>(set<span class="o">/</span><span class="m">2</span>).

<span class="p">    :- </span><span class="k">private</span>(attribute_<span class="o">/</span><span class="m">2</span>).
<span class="p">    :- </span><span class="k">dynamic</span>(attribute_<span class="o">/</span><span class="m">2</span>).

    get(<span class="nv">Var</span>, <span class="nv">Value</span>) <span class="o">:-</span>
        attribute_(<span class="nv">Var</span>, <span class="nv">Value</span>).

    set(<span class="nv">Var</span>, <span class="nv">Value</span>) <span class="o">:-</span>
        <span class="k">retractall</span>(attribute_(<span class="nv">Var</span>, <span class="nv">_</span>)),
        <span class="k">asserta</span>(attribute_(<span class="nv">Var</span>, <span class="nv">Value</span>).

<span class="p">:- </span><span class="k">end_category</span>.
</pre></div>
</div>
<p>In this case, each object importing the category will have its own clauses
for the <code class="docutils literal notranslate"><span class="pre">attribute_/2</span></code> private dynamic predicate.</p>
</section>
<section id="meta-predicates">
<span id="predicates-metadef"></span><h3>Meta-predicates<a class="headerlink" href="#meta-predicates" title="Link to this heading"></a></h3>
<p>Meta-predicates may be defined inside objects and categories as any other
predicate. A meta-predicate is declared using the
<a class="reference internal" href="../refman/directives/meta_predicate_1.html#directives-meta-predicate-1"><span class="std std-ref">meta_predicate/1</span></a> directive as described earlier in
this section. When defining a meta-predicate, the arguments in the
clause heads corresponding to the meta-arguments must be variables.
All meta-arguments are called in the context of the object or category
calling the meta-predicate. In particular, when sending a message that
corresponds to a meta-predicate, the meta-arguments are called in the
context of the object or category sending the message.</p>
<p>The most simple example is a meta-predicate with a meta-argument that is
called as a goal. E.g. the <a class="reference internal" href="../refman/methods/ignore_1.html#methods-ignore-1"><span class="std std-ref">ignore/1</span></a> built-in predicate could
be defined as:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">public</span>(ignore<span class="o">/</span><span class="m">1</span>).
<span class="p">:- </span><span class="k">meta_predicate</span>(<span class="k">ignore</span>(<span class="m">0</span>)).

<span class="k">ignore</span>(<span class="nv">Goal</span>) <span class="o">:-</span>
   (<span class="nv">Goal</span> <span class="o">-&gt;</span> <span class="k">true</span><span class="o">;</span> <span class="k">true</span>).
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">0</span></code> in the meta-predicate template tells us that the meta-argument is a
goal that will be called by the meta-predicate.</p>
<p>Some meta-predicates have meta-arguments that are not goals but
<a class="reference internal" href="../glossary.html#term-closure"><span class="xref std std-term">closures</span></a>. Logtalk supports the definition of meta-predicates
that are called with closures instead of goals as long as the definition uses
the <a class="reference internal" href="../refman/methods/call_N.html#methods-call-n"><span class="std std-ref">call/1-N</span></a> built-in predicate to call the closure with the
additional arguments. A classical example is a list mapping predicate:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">public</span>(map<span class="o">/</span><span class="m">2</span>).
<span class="p">:- </span><span class="k">meta_predicate</span>(map(<span class="m">1</span>, <span class="o">*</span>)).

map(<span class="nv">_</span>, []).
map(<span class="nv">Closure</span>, [<span class="nv">Arg</span>| <span class="nv">Args</span>]) <span class="o">:-</span>
    <span class="k">call</span>(<span class="nv">Closure</span>, <span class="nv">Arg</span>),
    map(<span class="nv">Closure</span>, <span class="nv">Args</span>).
</pre></div>
</div>
<p>Note that in this case the meta-predicate directive specifies that the
closure will be extended with exactly one additional argument. When
calling a meta-predicate, a closure can correspond to a user-defined
predicate, a built-in predicate, a <a class="reference internal" href="../glossary.html#term-lambda-expression"><span class="xref std std-term">lambda expression</span></a>, or a
control construct.</p>
<p>In some cases, it is not a meta-argument but one of its sub-terms that
is called as a goal or used as a closure. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">public</span>(call_all<span class="o">/</span><span class="m">1</span>).
<span class="p">:- </span><span class="k">meta_predicate</span>(call_all(<span class="o">::</span>)).

call_all([]).
call_all([<span class="nv">Goal</span>| <span class="nv">Goals</span>]) <span class="o">:-</span>
    <span class="k">call</span>(<span class="nv">Goal</span>),
    call_all(<span class="nv">Goals</span>).
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">::</span></code> mode indicator in the meta-predicate template allows the
corresponding argument in the meta-predicate definition to be a
non-variable term and instructs the compiler to look into the argument
sub-terms for goal and closure <a class="reference internal" href="../glossary.html#term-meta-variable"><span class="xref std std-term">meta-variables</span></a>.</p>
<p>When a meta-predicate calls another meta-predicate, both predicates require
<code class="docutils literal notranslate"><span class="pre">meta_predicate/1</span></code> directives. For example, the <code class="docutils literal notranslate"><span class="pre">map/2</span></code> meta-predicate
defined above is usually implemented by exchanging the argument order to
take advantage of first-argument indexing:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">meta_predicate</span>(map(<span class="m">1</span>, <span class="o">*</span>)).
map(<span class="nv">Closure</span>, <span class="nv">List</span>) <span class="o">:-</span>
    map_(<span class="nv">List</span>, <span class="nv">Closure</span>).

<span class="p">:- </span><span class="k">meta_predicate</span>(map_(<span class="o">*</span>, <span class="m">1</span>)).
map_([], <span class="nv">_</span>).
map_([<span class="nv">Head</span>| <span class="nv">Tail</span>], <span class="nv">Closure</span>) <span class="o">:-</span>
    <span class="k">call</span>(<span class="nv">Closure</span>, <span class="nv">Head</span>),
    map_(<span class="nv">Tail</span>, <span class="nv">Closure</span>).
</pre></div>
</div>
<p>Note that Logtalk, unlike most Prolog module systems, is not based on a
predicate prefixing mechanism. Thus, the meta-argument calling context
is not part of the meta-argument itself.</p>
</section>
<section id="lambda-expressions">
<span id="predicates-lambdas"></span><h3>Lambda expressions<a class="headerlink" href="#lambda-expressions" title="Link to this heading"></a></h3>
<p>The use of <a class="reference external" href="https://en.wikipedia.org/wiki/Lambda_calculus">lambda expressions</a>
as meta-predicate goal and <a class="reference internal" href="../glossary.html#term-closure"><span class="xref std std-term">closure</span></a> arguments often saves writing
auxiliary predicates for the sole purpose of calling the meta-predicates.
A simple example of a lambda expression is:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- meta::map([X,Y]&gt;&gt;(Y is 2*X), [1,2,3], Ys).
Ys = [2,4,6]
yes
</pre></div>
</div>
<p>In this example, a lambda expression, <code class="docutils literal notranslate"><span class="pre">[X,Y]&gt;&gt;(Y</span> <span class="pre">is</span> <span class="pre">2*X)</span></code>, is used as
an argument to the <code class="docutils literal notranslate"><span class="pre">map/3</span></code> list mapping predicate, defined in the
library object <code class="docutils literal notranslate"><span class="pre">meta</span></code>, in order to double the elements of a list of
integers. Using a lambda expression avoids writing an auxiliary
predicate for the sole purpose of doubling the list elements. The <em>lambda
parameters</em> are represented by the list <code class="docutils literal notranslate"><span class="pre">[X,Y]</span></code>, which is connected to
the <em>lambda goal</em>, <code class="docutils literal notranslate"><span class="pre">(Y</span> <span class="pre">is</span> <span class="pre">2*X)</span></code>, by the <code class="docutils literal notranslate"><span class="pre">(&gt;&gt;)/2</span></code> operator. The <code class="docutils literal notranslate"><span class="pre">map/3</span></code>
predicate calls the lambda goal with fresh/unique variables, represented
by the <code class="docutils literal notranslate"><span class="pre">X</span></code> and <code class="docutils literal notranslate"><span class="pre">Y</span></code> parameters, for each pair of elements of the second
and third list arguments.</p>
<p>Currying is supported. I.e. it is possible to write a lambda expression
whose goal is another lambda expression. The above example can be
rewritten as:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- meta::map([X]&gt;&gt;([Y]&gt;&gt;(Y is 2*X)), [1,2,3], Ys).
Ys = [2,4,6]
yes
</pre></div>
</div>
<p>Lambda expressions may also contain <em>lambda-free variables</em>. I.e. variables
that are global to the lambda expression and shared with the surrounding
meta-call context. Consider the following variant of the previous example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- between(1, 3, N), meta::map({N}/[X,Y]&gt;&gt;(Y is N*X), [1,2,3], L).
N = 1, L = [1,2,3] ;
N = 2, L = [2,4,6] ;
N = 3, L = [3,6,9]
yes
</pre></div>
</div>
<p>In this case, the lambda-free variable, <code class="docutils literal notranslate"><span class="pre">N</span></code>, bound by the <code class="docutils literal notranslate"><span class="pre">between/3</span></code>
goal, is fixed across all implicit calls made by the <code class="docutils literal notranslate"><span class="pre">map/3</span></code> goal.</p>
<p>A second example of free variables in a lambda expression using GNU Prolog
as the backend compiler:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- meta::map({Z}/[X,Y]&gt;&gt;(Z#=X+Y), [1,2,3], Zs).
Z = _#22(3..268435455)
Zs = [_#3(2..268435454),_#66(1..268435453),_#110(0..268435452)]
yes
</pre></div>
</div>
<p>The ISO Prolog construct <code class="docutils literal notranslate"><span class="pre">{}/1</span></code> is used for representing the lambda-free
variables as this representation is often associated with set
representation. Note that the order of the free variables is of no
consequence (on the other hand, a list is used for the lambda parameters
as their order does matter).</p>
<p>Both lambda free variables and lambda parameters can be any Prolog term.
Consider the following example by Markus Triska:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- meta::map([A-B,B-A]&gt;&gt;true, [1-a,2-b,3-c], Zs).
Zs = [a-1,b-2,c-3]
yes
</pre></div>
</div>
<p>Lambda expressions can be used, as expected, in non-deterministic
queries, as in the following example using SWI-Prolog as the backend
compiler and Markus Triska’s CLP(FD) library:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- meta::map({Z}/[X,Y]&gt;&gt;(clpfd:(Z#=X+Y)), Xs, Ys).
Xs = [],
Ys = [] ;
Xs = [_G1369],
Ys = [_G1378],
_G1369+_G1378#=Z ;
Xs = [_G1579, _G1582],
Ys = [_G1591, _G1594],
_G1582+_G1594#=Z,
_G1579+_G1591#=Z ;
Xs = [_G1789, _G1792, _G1795],
Ys = [_G1804, _G1807, _G1810],
_G1795+_G1810#=Z,
_G1792+_G1807#=Z,
_G1789+_G1804#=Z ;
...
</pre></div>
</div>
<p>As illustrated by the above examples, lambda expression syntax reuses
the ISO Prolog construct <code class="docutils literal notranslate"><span class="pre">{}/1</span></code> and the standard operators <code class="docutils literal notranslate"><span class="pre">(/)/2</span></code>
and <code class="docutils literal notranslate"><span class="pre">(&gt;&gt;)/2</span></code>, thus avoiding defining new operators, which is always
tricky for a portable system such as Logtalk. The operator <code class="docutils literal notranslate"><span class="pre">(&gt;&gt;)/2</span></code>
was chosen as it suggests an arrow, similar to the syntax used in other
languages such as OCaml and Haskell to connect lambda parameters with
lambda functions. This syntax was also chosen in order to simplify
parsing, error checking, and compilation of lambda expressions. The
full specification of the lambda expression syntax can be found in
the <a class="reference internal" href="../refman/grammar.html#grammar-lambdas"><span class="std std-ref">language grammar</span></a>.</p>
<p>The compiler checks whenever possible that all variables in a lambda
expression are either classified as free variables or as lambda
parameters. Non-classified variables in a lambda goal (including any
anonymous variables) should be regarded as a programming error. The
compiler also checks whenever possible if a variable is classified as
both a free variable and a lambda parameter. There are a few cases
where a variable playing a dual role is intended, but, in general, this
also results from a programming error. A third check verifies that no
lambda parameter variable is used elsewhere in a clause. Such cases
are either programming errors, when the variable appears before the
lambda expression, or bad programming style, when the variable is used
after the lambda expression. These linter warnings are controlled by
the <a class="reference internal" href="programming.html#flag-lambda-variables"><span class="std std-ref">lambda_variables</span></a> flag. Note that the
dynamic features of the language and lack of sufficient information at
compile-time may prevent the compiler from checking all uses of lambda
expressions. To improve linter coverage, compile code using lambda
expressions with the <a class="reference internal" href="programming.html#flag-optimize"><span class="std std-ref">optimize flag</span></a> turned on,
as that will result in additional cases of meta-arguments being
evaluated for possible optimizations.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Variables listed in lambda parameters must not be shared with
other goals in a clause.</p>
</div>
<p>An optimizing meta-predicate and lambda expression compiler, based on the
<a class="reference internal" href="expansion.html#expansion-expansion"><span class="std std-ref">term-expansion mechanism</span></a>, is provided as a
standard library for practical performance.</p>
<p>A common use of lambda expressions as closure meta-arguments is to workaround
closures always being extended by <em>appending</em> additional arguments to construct
a goal. For example, assume that we want to filter a list of atoms by a given
length. We can use the standard <code class="docutils literal notranslate"><span class="pre">atom_length/2</span></code> predicate despite the
argument order by writing:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>filter(<span class="nv">Length</span>, <span class="nv">Atoms</span>, <span class="nv">Filtered</span>) <span class="o">:-</span>
    meta<span class="o">::</span>include(<span class="k">{</span><span class="nv">Length</span><span class="k">}</span><span class="o">/</span>[<span class="nv">Atom</span>]<span class="o">&gt;&gt;</span><span class="k">atom_length</span>(<span class="nv">Atom</span>,<span class="nv">Length</span>), <span class="nv">Atoms</span>, <span class="nv">Filtered</span>).
</pre></div>
</div>
<p>But Logtalk supports a faster alternative by using predicate aliases to change
the argument order when calling library or built-in predicates:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">uses</span>(user, [
   <span class="k">atom_length</span>(<span class="nv">Atom</span>, <span class="nv">Length</span>) <span class="o">as</span> length_atom(<span class="nv">Length</span>, <span class="nv">Atom</span>)
]).

filter(<span class="nv">Length</span>, <span class="nv">Atoms</span>, <span class="nv">Filtered</span>) <span class="o">:-</span>
    meta<span class="o">::</span>include(length_atom(<span class="nv">Length</span>), <span class="nv">Atoms</span>, <span class="nv">Filtered</span>).
</pre></div>
</div>
<p>In this case, the performance is no longer dependent on compiling away lambda
expressions. The resulting code is also easier to read (and thus debug and
maintain). But the <code class="docutils literal notranslate"><span class="pre">uses/2</span></code> directive is implicitly defining an auxiliary
predicate, which is exactly what we wanted to avoid in the first place by
using a lambda expression.</p>
</section>
<section id="redefining-built-in-predicates">
<span id="predicates-redefining"></span><h3>Redefining built-in predicates<a class="headerlink" href="#redefining-built-in-predicates" title="Link to this heading"></a></h3>
<p>Logtalk built-in predicates and Prolog built-in predicates can be redefined
inside objects and categories. Although the redefinition of Logtalk built-in
predicates should be avoided, the support for redefining Prolog built-in
predicates is a practical requirement given the different sets of proprietary
built-in predicates provided by backend Prolog systems.</p>
<p>The compiler supports a <a class="reference internal" href="programming.html#flag-redefined-built-ins"><span class="std std-ref">redefined_built_ins</span></a>
flag, whose default value is <cite>silent</cite>, that can be set to <cite>warning</cite>
to alert the user of any redefined Logtalk or Prolog built-in predicate.</p>
<p>The redefinition of Prolog built-in predicates can be combined with the
<a class="reference internal" href="../refman/directives/conditional_compilation_directives.html#conditional-compilation-directives"><span class="std std-ref">conditional compilation directives</span></a>
when writing portable applications where some of the supported backends
don’t provide a built-in predicate found in the other backends. As an example,
consider the de facto standard <code class="docutils literal notranslate"><span class="pre">msort/2</span></code> predicate (which sorts a list while
keeping duplicates). This predicate is provided as a built-in predicate in most
but not all backends. The <code class="docutils literal notranslate"><span class="pre">list</span></code> library object includes the code:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">if</span>(<span class="k">predicate_property</span>(msort(<span class="nv">_</span>, <span class="nv">_</span>), built_in)).

    msort(<span class="nv">List</span>, <span class="nv">Sorted</span>) <span class="o">:-</span>
        <span class="k">{</span>msort(<span class="nv">List</span>, <span class="nv">Sorted</span>)<span class="k">}</span>.

<span class="p">:- </span><span class="k">else</span>.

    length(<span class="nv">List</span>, <span class="nv">Length</span>) <span class="o">:-</span>
        ...

<span class="p">:- </span><span class="k">endif</span>.
</pre></div>
</div>
<p>I.e. the object will use the built-in predicate when available. Otherwise,
it will use the predicate definition provided by the <code class="docutils literal notranslate"><span class="pre">list</span></code> object.</p>
<p>The redefinition of built-in predicates can also be accomplished using
<a class="reference internal" href="../glossary.html#term-predicate-shorthand"><span class="xref std std-term">predicate shorthands</span></a>. This can be useful
when porting code while minimizing the changes. For example, assume
that existing code uses the <code class="docutils literal notranslate"><span class="pre">format/2</span></code> de facto standard predicate
for writing messages. To convert the code to use the
<a class="reference internal" href="printing.html#printing-printing"><span class="std std-ref">message printing mechanism</span></a>, we could write:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">uses</span>(logtalk, [
    print_message(comment, core, <span class="nv">Format</span><span class="o">+</span><span class="nv">Arguments</span>) <span class="o">as</span> format(<span class="nv">Format</span>, <span class="nv">Arguments</span>)
]).

process(<span class="nv">Crate</span>, <span class="nv">Contents</span>) <span class="o">:-</span>
    format(<span class="s">&#39;Processing crate ~w...&#39;</span>, [<span class="nv">Crate</span>]),
    ...,
    format(<span class="s">&#39;Filing with ~w...&#39;</span>, [<span class="nv">Contents</span>]),
    ....
</pre></div>
</div>
<p>The predicate shorthand instructs the compiler to rewrite all <code class="docutils literal notranslate"><span class="pre">format/2</span></code>
goals as <code class="docutils literal notranslate"><span class="pre">logtalk::print_message/3</span></code> goals, thus allowing us to reuse
the code without changes.</p>
</section>
</section>
<section id="definite-clause-grammar-rules">
<span id="predicates-dcgs"></span><h2>Definite clause grammar rules<a class="headerlink" href="#definite-clause-grammar-rules" title="Link to this heading"></a></h2>
<p>Definite clause grammar rules (DCGs) provide a convenient notation to
represent the parsing and rewrite rules common of most grammars in
Prolog. In Logtalk, definite clause grammar rules can be encapsulated
in objects and categories. Currently, the ISO/IEC WG17 group is working
on a draft specification for a definite clause grammars Prolog standard.
Therefore, in the meantime, Logtalk follows the common practice of Prolog
compilers supporting definite clause grammars, extending it to support
calling grammar rules contained in categories and objects. A common
example of a definite clause grammar is the definition of a set of rules
for parsing simple arithmetic expressions:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(calculator).

<span class="p">    :- </span><span class="k">public</span>(parse<span class="o">/</span><span class="m">2</span>).

    parse(<span class="nv">Expression</span>, <span class="nv">Value</span>) <span class="o">:-</span>
        <span class="k">phrase</span>(expr(<span class="nv">Value</span>), <span class="nv">Expression</span>).

    expr(<span class="nv">Z</span>) <span class="o">--&gt;</span> term(<span class="nv">X</span>), <span class="s">&quot;+&quot;</span>, expr(<span class="nv">Y</span>), <span class="k">{</span><span class="nv">Z</span> <span class="k">is</span> <span class="nv">X</span> <span class="o">+</span> <span class="nv">Y</span><span class="k">}</span>.
    expr(<span class="nv">Z</span>) <span class="o">--&gt;</span> term(<span class="nv">X</span>), <span class="s">&quot;-&quot;</span>, expr(<span class="nv">Y</span>), <span class="k">{</span><span class="nv">Z</span> <span class="k">is</span> <span class="nv">X</span> <span class="o">-</span> <span class="nv">Y</span><span class="k">}</span>.
    expr(<span class="nv">X</span>) <span class="o">--&gt;</span> term(<span class="nv">X</span>).

    term(<span class="nv">Z</span>) <span class="o">--&gt;</span> <span class="k">number</span>(<span class="nv">X</span>), <span class="s">&quot;*&quot;</span>, term(<span class="nv">Y</span>), <span class="k">{</span><span class="nv">Z</span> <span class="k">is</span> <span class="nv">X</span> <span class="o">*</span> <span class="nv">Y</span><span class="k">}</span>.
    term(<span class="nv">Z</span>) <span class="o">--&gt;</span> <span class="k">number</span>(<span class="nv">X</span>), <span class="s">&quot;/&quot;</span>, term(<span class="nv">Y</span>), <span class="k">{</span><span class="nv">Z</span> <span class="k">is</span> <span class="nv">X</span> <span class="o">/</span> <span class="nv">Y</span><span class="k">}</span>.
    term(<span class="nv">Z</span>) <span class="o">--&gt;</span> <span class="k">number</span>(<span class="nv">Z</span>).

    <span class="k">number</span>(<span class="nv">C</span>) <span class="o">--&gt;</span> <span class="s">&quot;+&quot;</span>, <span class="k">number</span>(<span class="nv">C</span>).
    <span class="k">number</span>(<span class="nv">C</span>) <span class="o">--&gt;</span> <span class="s">&quot;-&quot;</span>, <span class="k">number</span>(<span class="nv">X</span>), <span class="k">{</span><span class="nv">C</span> <span class="k">is</span> <span class="o">-</span><span class="nv">X</span><span class="k">}</span>.
    <span class="k">number</span>(<span class="nv">X</span>) <span class="o">--&gt;</span> [<span class="nv">C</span>], <span class="k">{</span><span class="m">0&#39;0</span> <span class="o">=&lt;</span> <span class="nv">C</span>, <span class="nv">C</span> <span class="o">=&lt;</span> <span class="m">0&#39;9</span>, <span class="nv">X</span> <span class="k">is</span> <span class="nv">C</span> <span class="o">-</span> <span class="m">0&#39;0</span><span class="k">}</span>.

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>After compiling and loading this object, we can test the grammar rules
using the <code class="docutils literal notranslate"><span class="pre">parse/2</span></code> message:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- calculator::parse(&quot;1+2-3*4&quot;, Result).

Result = -9
yes
</pre></div>
</div>
<p>The non-terminals can be called from predicates using the private built-in
methods <a class="reference internal" href="../refman/methods/phrase_2.html#methods-phrase-2"><span class="std std-ref">phrase/2</span></a> and <a class="reference internal" href="../refman/methods/phrase_3.html#methods-phrase-3"><span class="std std-ref">phrase/3</span></a> as shown in the
example above. When we want to use the built-in methods <code class="docutils literal notranslate"><span class="pre">phrase/2</span></code> and
<code class="docutils literal notranslate"><span class="pre">phrase/3</span></code>, the non-terminal used as in the first argument must be within
the scope of the <em>sender</em>. For the above example, assuming that we want the
predicate corresponding to the <code class="docutils literal notranslate"><span class="pre">expr//1</span></code> non-terminal to be public,
the corresponding scope directive would be:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">public</span>(expr<span class="o">//</span><span class="m">1</span>).
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">//</span></code> infix operator used above tells the Logtalk compiler that the
scope directive refers to a grammar rule non-terminal, not to a predicate.
The idea is that the predicate corresponding to the translation of the
<code class="docutils literal notranslate"><span class="pre">expr//1</span></code> non-terminal will have a number of arguments equal to one plus
the number of additional arguments necessary for processing the implicit
difference list of tokens.</p>
<p>In the body of a grammar rule, we can call rules that are inherited from
ancestor objects, imported from categories, or contained in other
objects. This is accomplished by using non-terminals as messages. Using
a non-terminal as a message to <em>self</em> allows us to call grammar rules in
categories and ancestor objects. To call grammar rules encapsulated in
other objects, we use a non-terminal as a message to those objects.
Consider the following example, containing grammar rules for parsing
natural language sentences:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(sentence,
    <span class="k">imports</span>(determiners, nouns, verbs)).

<span class="p">    :- </span><span class="k">public</span>(parse<span class="o">/</span><span class="m">2</span>).

    parse(<span class="nv">List</span>, <span class="k">true</span>) <span class="o">:-</span>
        <span class="k">phrase</span>(sentence, <span class="nv">List</span>).
    parse(<span class="nv">_</span>, <span class="k">false</span>).

    sentence <span class="o">--&gt;</span> noun_phrase, verb_phrase.

    noun_phrase <span class="o">--&gt;</span> <span class="o">::</span>determiner, <span class="o">::</span>noun.
    noun_phrase <span class="o">--&gt;</span> <span class="o">::</span>noun.

    verb_phrase <span class="o">--&gt;</span> <span class="o">::</span>verb.
    verb_phrase <span class="o">--&gt;</span> <span class="o">::</span>verb, noun_phrase.

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>The categories imported by the object would contain the necessary
grammar rules for parsing determiners, nouns, and verbs. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">category</span>(determiners).

<span class="p">    :- </span><span class="k">private</span>(determiner<span class="o">//</span><span class="m">0</span>).

    determiner <span class="o">--&gt;</span> [the].
    determiner <span class="o">--&gt;</span> [a].

<span class="p">:- </span><span class="k">end_category</span>.
</pre></div>
</div>
<p>Along with the message-sending operators (<code class="docutils literal notranslate"><span class="pre">(::)/1</span></code>, <code class="docutils literal notranslate"><span class="pre">(::)/2</span></code>, and <code class="docutils literal notranslate"><span class="pre">(^^)/1</span></code>),
we may also use other control constructs such as <code class="docutils literal notranslate"><span class="pre">(&lt;&lt;)/2</span></code>, <code class="docutils literal notranslate"><span class="pre">(\+)/1</span></code>, <code class="docutils literal notranslate"><span class="pre">!/0</span></code>,
<code class="docutils literal notranslate"><span class="pre">(;)/2</span></code>, <code class="docutils literal notranslate"><span class="pre">(-&gt;)/2</span></code>, <code class="docutils literal notranslate"><span class="pre">{}/1</span></code>, <code class="docutils literal notranslate"><span class="pre">call//1-N</span></code>, and <code class="docutils literal notranslate"><span class="pre">catch/3</span></code> in the body of a
grammar rule. When using a backend Prolog compiler that supports modules, we may
also use the <code class="docutils literal notranslate"><span class="pre">(:)/2</span></code> control construct.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The semantics of <code class="docutils literal notranslate"><span class="pre">(\+)/1</span></code> and <code class="docutils literal notranslate"><span class="pre">(-&gt;)/2</span></code> control constructs in grammar rules
with a terminal or a non-terminal in the <strong>first</strong> argument are problematic due
to unrestricted lookahead that may or may not be valid depending on the grammar
rule implicit arguments. By default, the linter will print warnings for such
calls (controlled by the <a class="reference internal" href="programming.html#flag-grammar-rules"><span class="std std-ref">grammar_rules</span></a> flag).
Preferably restrict the use of the <code class="docutils literal notranslate"><span class="pre">(\+)/1</span></code> control construct to <code class="docutils literal notranslate"><span class="pre">{}/1</span></code>
arguments and the use of the <code class="docutils literal notranslate"><span class="pre">(-&gt;)/2</span></code> control construct to <code class="docutils literal notranslate"><span class="pre">{}/1</span></code> test
arguments.</p>
</div>
<p>In addition, grammar rules may contain meta-calls (a variable taking the place
of a non-terminal), which are translated to calls of the built-in method
<code class="docutils literal notranslate"><span class="pre">phrase//1</span></code>. The <a class="reference internal" href="../refman/directives/meta_non_terminal_1.html#directives-meta-non-terminal-1"><span class="std std-ref">meta_non_terminal/1</span></a> directive allows the
declaration of non-terminals that have arguments that are meta-called from
grammar rules. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">meta_non_terminal</span>(zero_or_more(<span class="m">1</span>, <span class="o">*</span>)).

zero_or_more(<span class="nv">Closure</span>, [<span class="nv">Terminal</span>| <span class="nv">Terminals</span>]) <span class="o">--&gt;</span>
    <span class="k">call</span>(<span class="nv">Closure</span>, <span class="nv">Terminal</span>), <span class="o">!</span>, zero_or_more(<span class="nv">Closure</span>, <span class="nv">Terminals</span>).
zero_or_more(<span class="nv">_</span>, []) <span class="o">--&gt;</span>
    [].
</pre></div>
</div>
<p>You may have noticed that Logtalk defines <a class="reference internal" href="../refman/control/external_call_1.html#control-external-call-1"><span class="std std-ref">{}/1</span></a>
as a control construct for bypassing the compiler when compiling a clause body
goal. As exemplified above, this is the same control construct that is used in
grammar rules for bypassing the expansion of rule body goals when a rule is
converted into a clause. Both control constructs can be combined in order to
call a goal from a grammar rule body, while bypassing at the same time the
Logtalk compiler. Consider the following example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>bar <span class="o">:-</span>
    <span class="k">write</span>(<span class="s">&#39;bar predicate called&#39;</span>), <span class="k">nl</span>.


<span class="p">:- </span><span class="k">object</span>(bypass).

<span class="p">    :- </span><span class="k">public</span>(foo<span class="o">//</span><span class="m">0</span>).

    foo <span class="o">--&gt;</span> <span class="k">{{</span>bar<span class="k">}}</span>.

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>After compiling and loading this code, we may try the following query:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- logtalk &lt;&lt; phrase(bypass::foo, _, _).

bar predicate called
yes
</pre></div>
</div>
<p>This is the expected result, as the expansion of the grammar rule into a
clause leaves the <code class="docutils literal notranslate"><span class="pre">{bar}</span></code> goal untouched, which, in turn, is converted
into the goal <code class="docutils literal notranslate"><span class="pre">bar</span></code> when the clause is compiled. Note that we tested
the <code class="docutils literal notranslate"><span class="pre">bypass::foo//0</span></code> non-terminal by calling the <code class="docutils literal notranslate"><span class="pre">phrase/3</span></code> built-in
method in the context of the <code class="docutils literal notranslate"><span class="pre">logtalk</span></code> built-in object. This workaround
is necessary due to the Prolog backend implementation of the <code class="docutils literal notranslate"><span class="pre">phrase/3</span></code>
predicate not being aware of the Logtalk <code class="docutils literal notranslate"><span class="pre">(::)/2</span></code> message-sending control
construct semantics.</p>
<p>A grammar rule non-terminal may be declared as dynamic or discontiguous,
as any object predicate, using the same <code class="docutils literal notranslate"><span class="pre">Name//Arity</span></code> notation
illustrated above for the scope directives. In addition, grammar rule
non-terminals can be documented using the <a class="reference internal" href="../refman/directives/info_2.html#directives-info-2"><span class="std std-ref">info/2</span></a>
directive, as in the following example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">public</span>(sentence<span class="o">//</span><span class="m">0</span>).

<span class="p">:- </span><span class="k">info</span>(sentence<span class="o">//</span><span class="m">0</span>, [
    comment <span class="k">is</span> <span class="s">&#39;Rewrites sentence into noun and verb phrases.&#39;</span>
]).
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Future Logtalk versions may compile grammar rules differently from Prolog
traditional compilation to prevent name clashes between non-terminals and
predicates. Therefore, you should always call non-terminals from predicates
using the <code class="docutils literal notranslate"><span class="pre">phrase/2-3</span></code> built-in methods and always call predicates from
grammar rules using the <code class="docutils literal notranslate"><span class="pre">call//1</span></code> built-in method. This recommended
practice, besides making your code forward compatible with future Logtalk
versions, also makes the code more clear. The linter prints warnings when
these guidelines are not followed (notably, when a predicate is called as
a non-terminal or a non-terminal is called as a predicate).</p>
</div>
</section>
<section id="built-in-methods">
<span id="predicates-methods"></span><h2>Built-in methods<a class="headerlink" href="#built-in-methods" title="Link to this heading"></a></h2>
<p>Built-in methods are built-in object and category predicates. These include
methods to access message execution context, to find sets of solutions, to
inspect objects, for database handling, for term and goal expansion, and
for printing messages. Some of them are counterparts to standard Prolog
built-in predicates that take into account Logtalk semantics. Similar to
Prolog built-in predicates, built-in methods cannot be redefined.</p>
<section id="logic-and-control-methods">
<span id="predicates-logic"></span><h3>Logic and control methods<a class="headerlink" href="#logic-and-control-methods" title="Link to this heading"></a></h3>
<p>The <a class="reference internal" href="../refman/methods/cut_0.html#methods-cut-0"><span class="std std-ref">!/0</span></a>, <a class="reference internal" href="../refman/methods/true_0.html#methods-true-0"><span class="std std-ref">true/0</span></a>, <a class="reference internal" href="../refman/methods/fail_0.html#methods-fail-0"><span class="std std-ref">fail/0</span></a>,
<a class="reference internal" href="../refman/methods/false_0.html#methods-false-0"><span class="std std-ref">false/0</span></a>, and <a class="reference internal" href="../refman/methods/repeat_0.html#methods-repeat-0"><span class="std std-ref">repeat/0</span></a> standard control
constructs and logic predicates are interpreted as built-in public methods
and thus can be used as messages to any object. In practice, they are only
used as messages when sending multiple messages to the same object
(see the section on <a class="reference internal" href="messages.html#messages-broadcasting"><span class="std std-ref">message broadcasting</span></a>).</p>
</section>
<section id="execution-context-methods">
<span id="predicates-context"></span><h3>Execution context methods<a class="headerlink" href="#execution-context-methods" title="Link to this heading"></a></h3>
<p>Logtalk defines five built-in private methods to access an object
execution context. These methods are in the common usage scenarios
translated to a single unification performed at compile-time with a
clause head context argument. Therefore, they can be freely used without
worrying about performance penalties. When called from inside a
category, these methods refer to the execution context of the object
importing the category. These methods are private and cannot be used as
messages to objects.</p>
<p>To find the object that received the message under execution, we may use
the <a class="reference internal" href="../refman/methods/self_1.html#methods-self-1"><span class="std std-ref">self/1</span></a> method. We may also retrieve the object that has
sent the message under execution using the <a class="reference internal" href="../refman/methods/sender_1.html#methods-sender-1"><span class="std std-ref">sender/1</span></a> method.</p>
<p>The method <a class="reference internal" href="../refman/methods/this_1.html#methods-this-1"><span class="std std-ref">this/1</span></a> enables us to
retrieve the name of the object for which the predicate clause whose
body is being executed is defined instead of using the name directly.
This helps to avoid breaking the code if we decide to change the object
name and forget to change the name references. This method may also be
used from within a category. In this case, the method returns the object
importing the category on whose behalf the predicate clause is being
executed.</p>
<p>Here is a short example including calls to these three object execution
context methods:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(test).

<span class="p">    :- </span><span class="k">public</span>(test<span class="o">/</span><span class="m">0</span>).

    test <span class="o">:-</span>
        <span class="k">this</span>(<span class="nv">This</span>),
        <span class="k">write</span>(<span class="s">&#39;Calling predicate definition in &#39;</span>),
        <span class="k">writeq</span>(<span class="nv">This</span>), <span class="k">nl</span>,
        <span class="k">self</span>(<span class="nv">Self</span>),
        <span class="k">write</span>(<span class="s">&#39;to answer a message received by &#39;</span>),
        <span class="k">writeq</span>(<span class="nv">Self</span>), <span class="k">nl</span>,
        <span class="k">sender</span>(<span class="nv">Sender</span>),
        <span class="k">write</span>(<span class="s">&#39;that was sent by &#39;</span>),
        <span class="k">writeq</span>(<span class="nv">Sender</span>), <span class="k">nl</span>, <span class="k">nl</span>.

<span class="p">:- </span><span class="k">end_object</span>.


<span class="p">:- </span><span class="k">object</span>(descendant,
    <span class="k">extends</span>(test)).

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>After compiling and loading these two objects, we can try the following
goal:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- descendant::test.

Calling predicate definition in test
to answer a message received by descendant
that was sent by user
yes
</pre></div>
</div>
<p>Note that the goals <code class="docutils literal notranslate"><span class="pre">self(Self)</span></code>, <code class="docutils literal notranslate"><span class="pre">sender(Sender)</span></code>, and
<code class="docutils literal notranslate"><span class="pre">this(This)</span></code>, being translated to unifications with the clause head
context arguments at compile-time, are effectively removed from the
clause body. Therefore, a clause such as:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>predicate(<span class="nv">Arg</span>) <span class="o">:-</span>
    <span class="k">self</span>(<span class="nv">Self</span>),
    <span class="k">atom</span>(<span class="nv">Arg</span>),
    ... .
</pre></div>
</div>
<p>is compiled with the goal <code class="docutils literal notranslate"><span class="pre">atom(Arg)</span></code> as the first condition on the
clause body. As such, the use of these context execution methods does not
interfere with the optimizations that some Prolog compilers perform when
the first clause body condition is a call to a built-in type-test
predicate or a comparison operator.</p>
<p>For parametric objects and categories, the method <a class="reference internal" href="../refman/methods/parameter_2.html#methods-parameter-2"><span class="std std-ref">parameter/2</span></a>
enables us to retrieve current parameter values (see the section on
<a class="reference internal" href="objects.html#objects-parametric"><span class="std std-ref">parametric objects</span></a> for a detailed description).
For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(block(<span class="nv">_Color</span>)).

<span class="p">    :- </span><span class="k">public</span>(test<span class="o">/</span><span class="m">0</span>).

    test <span class="o">:-</span>
        <span class="k">parameter</span>(<span class="m">1</span>, <span class="nv">Color</span>),
        <span class="k">write</span>(<span class="s">&#39;Color parameter value is &#39;</span>),
        <span class="k">writeq</span>(<span class="nv">Color</span>), <span class="k">nl</span>.

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>An alternative to the <code class="docutils literal notranslate"><span class="pre">parameter/2</span></code> predicate is to use
<a class="reference internal" href="../glossary.html#term-parameter-variable"><span class="xref std std-term">parameter variables</span></a>:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(block(<span class="nv">_Color_</span>)).

<span class="p">    :- </span><span class="k">public</span>(test<span class="o">/</span><span class="m">0</span>).

    test <span class="o">:-</span>
        <span class="k">write</span>(<span class="s">&#39;Color parameter value is &#39;</span>),
        <span class="k">writeq</span>(<span class="nv">_Color_</span>), <span class="k">nl</span>.

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>After compiling and loading either version of the object, we can try the
following goal:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- block(blue)::test.

Color parameter value is blue
yes
</pre></div>
</div>
<p>Calls to the <code class="docutils literal notranslate"><span class="pre">parameter/2</span></code> method are translated to a compile-time
unification when the second argument is a variable. When the second
argument is bound, the calls are translated to a call to the built-in
predicate <code class="docutils literal notranslate"><span class="pre">arg/3</span></code>.</p>
<p>When type-checking predicate arguments, it is often useful to include
the predicate execution context when reporting an argument error. The
<a class="reference internal" href="../refman/methods/context_1.html#methods-context-1"><span class="std std-ref">context/1</span></a> method provides access to that context. For
example, assume a predicate <code class="docutils literal notranslate"><span class="pre">foo/2</span></code> that takes an atom and an integer
as arguments. We could type-check the arguments by writing (using the
library <code class="docutils literal notranslate"><span class="pre">type</span></code> object):</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>foo(<span class="nv">A</span>, <span class="nv">N</span>) <span class="o">:-</span>
    <span class="c">% type-check arguments</span>
    <span class="k">context</span>(<span class="nv">Context</span>),
    type<span class="o">::</span>check(atom, <span class="nv">A</span>, <span class="nv">Context</span>),
    type<span class="o">::</span>check(integer, <span class="nv">N</span>, <span class="nv">Context</span>),
    <span class="c">% arguments are fine; go ahead</span>
    ... .
</pre></div>
</div>
</section>
<section id="error-handling-and-throwing-methods">
<span id="predicates-errors"></span><h3>Error handling and throwing methods<a class="headerlink" href="#error-handling-and-throwing-methods" title="Link to this heading"></a></h3>
<p>Besides the <a class="reference internal" href="../refman/methods/catch_3.html#methods-catch-3"><span class="std std-ref">catch/3</span></a> and <a class="reference internal" href="../refman/methods/throw_1.html#methods-throw-1"><span class="std std-ref">throw/1</span></a> methods inherited from
Prolog, Logtalk also provides a set of convenience methods to throw
standard <code class="docutils literal notranslate"><span class="pre">error/2</span></code> exception terms:
<a class="reference internal" href="../refman/methods/instantiation_error_0.html#methods-instantiation-error-0"><span class="std std-ref">instantiation_error/0</span></a>,
<a class="reference internal" href="../refman/methods/uninstantiation_error_1.html#methods-uninstantiation-error-1"><span class="std std-ref">uninstantiation_error/1</span></a>,
<a class="reference internal" href="../refman/methods/type_error_2.html#methods-type-error-2"><span class="std std-ref">type_error/2</span></a>,
<a class="reference internal" href="../refman/methods/domain_error_2.html#methods-domain-error-2"><span class="std std-ref">domain_error/2</span></a>,
<a class="reference internal" href="../refman/methods/existence_error_2.html#methods-existence-error-2"><span class="std std-ref">existence_error/2</span></a>,
<a class="reference internal" href="../refman/methods/permission_error_3.html#methods-permission-error-3"><span class="std std-ref">permission_error/3</span></a>,
<a class="reference internal" href="../refman/methods/representation_error_1.html#methods-representation-error-1"><span class="std std-ref">representation_error/1</span></a>,
<a class="reference internal" href="../refman/methods/evaluation_error_1.html#methods-evaluation-error-1"><span class="std std-ref">evaluation_error/1</span></a>,
<a class="reference internal" href="../refman/methods/resource_error_1.html#methods-resource-error-1"><span class="std std-ref">resource_error/1</span></a>,
<a class="reference internal" href="../refman/methods/syntax_error_1.html#methods-syntax-error-1"><span class="std std-ref">syntax_error/1</span></a>, and
<a class="reference internal" href="../refman/methods/system_error_0.html#methods-system-error-0"><span class="std std-ref">system_error/0</span></a>. When using these methods, the second argument
of the <code class="docutils literal notranslate"><span class="pre">error/2</span></code> exception term is bound to the execution context (as it
would be provided by the <a class="reference internal" href="../refman/methods/context_1.html#methods-context-1"><span class="std std-ref">context/1</span></a> method).</p>
</section>
<section id="database-methods">
<span id="predicates-database"></span><h3>Database methods<a class="headerlink" href="#database-methods" title="Link to this heading"></a></h3>
<p>Logtalk provides a set of built-in methods for <a class="reference internal" href="../glossary.html#term-object-database"><span class="xref std std-term">object database</span></a> handling
similar to the usual database Prolog predicates:
<a class="reference internal" href="../refman/methods/abolish_1.html#methods-abolish-1"><span class="std std-ref">abolish/1</span></a>,
<a class="reference internal" href="../refman/methods/asserta_1.html#methods-asserta-1"><span class="std std-ref">asserta/1</span></a>,
<a class="reference internal" href="../refman/methods/assertz_1.html#methods-assertz-1"><span class="std std-ref">assertz/1</span></a>,
<a class="reference internal" href="../refman/methods/clause_2.html#methods-clause-2"><span class="std std-ref">clause/2</span></a>,
<a class="reference internal" href="../refman/methods/retract_1.html#methods-retract-1"><span class="std std-ref">retract/1</span></a>, and
<a class="reference internal" href="../refman/methods/retractall_1.html#methods-retractall-1"><span class="std std-ref">retractall/1</span></a>. These
methods always operate on the database of the object receiving the corresponding
message. When called locally, these predicates take into account any
<a class="reference internal" href="../refman/directives/uses_2.html#directives-uses-2"><span class="std std-ref">uses/2</span></a> or <a class="reference internal" href="../refman/directives/use_module_2.html#directives-use-module-2"><span class="std std-ref">use_module/2</span></a> directives that refer
to the dynamic predicate being handled. For example, in the following object, the
clauses for the <code class="docutils literal notranslate"><span class="pre">data/1</span></code> predicate are retracted and asserted in <code class="docutils literal notranslate"><span class="pre">user</span></code> due to
the <code class="docutils literal notranslate"><span class="pre">uses/2</span></code> directive:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(an_object).

<span class="p">    :- </span><span class="k">uses</span>(user, [data<span class="o">/</span><span class="m">1</span>]).

<span class="p">    :- </span><span class="k">public</span>(some_predicate<span class="o">/</span><span class="m">1</span>).
    some_predicate(<span class="nv">Arg</span>) <span class="o">:-</span>
        <span class="k">retractall</span>(data(<span class="nv">_</span>)),
        <span class="k">assertz</span>(data(<span class="nv">Arg</span>)).

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>When working with dynamic grammar rule non-terminals, you may use the built-in
method <a class="reference internal" href="../refman/methods/expand_term_2.html#methods-expand-term-2"><span class="std std-ref">expand_term/2</span></a> convert a grammar rule into a clause that
can then be used with the database methods.</p>
<p>Logtalk also supports <code class="docutils literal notranslate"><span class="pre">asserta/2</span></code>, <code class="docutils literal notranslate"><span class="pre">assertz/2</span></code>, <code class="docutils literal notranslate"><span class="pre">clause/3</span></code>, and
<code class="docutils literal notranslate"><span class="pre">erase/1</span></code> built-in methods when run with a backend that supports the
corresponding legacy built-in predicates that work with
<a class="reference internal" href="../glossary.html#term-clause-reference"><span class="xref std std-term">clause references</span></a>.</p>
</section>
<section id="meta-call-methods">
<span id="predicates-metacalls"></span><h3>Meta-call methods<a class="headerlink" href="#meta-call-methods" title="Link to this heading"></a></h3>
<p>Logtalk supports the generalized <a class="reference internal" href="../refman/methods/call_N.html#methods-call-n"><span class="std std-ref">call/1-N</span></a> meta-predicate. This
built-in private meta-predicate must be used in the implementation of
meta-predicates that work with <a class="reference internal" href="../glossary.html#term-closure"><span class="xref std std-term">closures</span></a> instead of goals.
In addition, Logtalk supports the built-in private meta-predicates
<a class="reference internal" href="../refman/methods/ignore_1.html#methods-ignore-1"><span class="std std-ref">ignore/1</span></a>, <a class="reference internal" href="../refman/methods/once_1.html#methods-once-1"><span class="std std-ref">once/1</span></a>, and
<a class="reference internal" href="../refman/methods/not_1.html#methods-not-1"><span class="std std-ref">(\+)/1</span></a>. These methods cannot be used as messages to objects.</p>
</section>
<section id="all-solutions-methods">
<span id="predicates-solutions"></span><h3>All solutions methods<a class="headerlink" href="#all-solutions-methods" title="Link to this heading"></a></h3>
<p>The usual all solutions meta-predicates are built-in private methods in
Logtalk: <a class="reference internal" href="../refman/methods/bagof_3.html#methods-bagof-3"><span class="std std-ref">bagof/3</span></a>, <a class="reference internal" href="../refman/methods/findall_3.html#methods-findall-3"><span class="std std-ref">findall/3</span></a>,
<a class="reference internal" href="../refman/methods/findall_4.html#methods-findall-4"><span class="std std-ref">findall/4</span></a>, and <a class="reference internal" href="../refman/methods/setof_3.html#methods-setof-3"><span class="std std-ref">setof/3</span></a>. There is also a
<a class="reference internal" href="../refman/methods/forall_2.html#methods-forall-2"><span class="std std-ref">forall/2</span></a> method that implements generate-and-test loops.
These methods cannot be used as messages to objects.</p>
</section>
<section id="reflection-methods">
<span id="predicates-reflection"></span><h3>Reflection methods<a class="headerlink" href="#reflection-methods" title="Link to this heading"></a></h3>
<p>Logtalk provides a comprehensive set of built-in predicates and built-in
methods for querying about entities and predicates. Some of the information,
however, requires that the source files are compiled with the
<a class="reference internal" href="programming.html#flag-source-data"><span class="std std-ref">source_data</span></a> flag turned on.</p>
<p>The <a class="reference internal" href="reflection.html#reflection-reflection"><span class="std std-ref">reflection API</span></a> supports two different views
on entities and their contents, which we may call the <em>transparent box view</em>
and the <em>black box view</em>. In the transparent box view, we look into an entity
disregarding how it will be used and returning all information available
on it, including predicate declarations and predicate definitions. This
view is supported by the entity property built-in predicates. In the
black box view, we look into an entity from a usage point of view using
built-in methods for inspecting object operators and predicates that are
within scope from where we are making the call:
<a class="reference internal" href="../refman/methods/current_op_3.html#methods-current-op-3"><span class="std std-ref">current_op/3</span></a>, which returns operator specifications;
<a class="reference internal" href="../refman/methods/predicate_property_2.html#methods-predicate-property-2"><span class="std std-ref">predicate_property/2</span></a>, which returns predicate properties;
and <a class="reference internal" href="../refman/methods/current_predicate_1.html#methods-current-predicate-1"><span class="std std-ref">current_predicate/1</span></a>, which enables us to query about
user-defined predicate definitions. See below for a more detailed description
of these methods.</p>
</section>
<section id="definite-clause-grammar-parsing-methods-and-non-terminals">
<span id="predicates-parsing"></span><h3>Definite clause grammar parsing methods and non-terminals<a class="headerlink" href="#definite-clause-grammar-parsing-methods-and-non-terminals" title="Link to this heading"></a></h3>
<p>Logtalk supports two definite clause grammar parsing built-in private
methods, <a class="reference internal" href="../refman/methods/phrase_2.html#methods-phrase-2"><span class="std std-ref">phrase/2</span></a> and <a class="reference internal" href="../refman/methods/phrase_3.html#methods-phrase-3"><span class="std std-ref">phrase/3</span></a>, with definitions
similar to the predicates with the same name found on most Prolog
compilers that support definite clause grammars. These methods cannot be
used as messages to objects.</p>
<p>Logtalk also supports <a class="reference internal" href="../refman/methods/phrase_1.html#methods-phrase-1"><span class="std std-ref">phrase//1</span></a>, <a class="reference internal" href="../refman/methods/call_1.html#methods-call-1"><span class="std std-ref">call//1-N</span></a>, and
<a class="reference internal" href="../refman/methods/eos_0.html#methods-eos-0"><span class="std std-ref">eos//0</span></a> built-in non-terminals.
The <code class="docutils literal notranslate"><span class="pre">call//1-N</span></code> non-terminals take a <a class="reference internal" href="../glossary.html#term-closure"><span class="xref std std-term">closure</span></a> (which can be a lambda
expression) plus zero or more additional arguments and are processed by
appending the input list of tokens and the list of remaining tokens to
the arguments.</p>
</section>
</section>
<section id="predicate-properties">
<span id="predicates-properties"></span><h2>Predicate properties<a class="headerlink" href="#predicate-properties" title="Link to this heading"></a></h2>
<p>We can find the properties of visible predicates by calling the
<a class="reference internal" href="../refman/methods/predicate_property_2.html#methods-predicate-property-2"><span class="std std-ref">predicate_property/2</span></a> built-in method. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- bar::predicate_property(foo(_), Property).
</pre></div>
</div>
<p>Note that this method takes into account the predicate’s scope declarations.
In the above example, the call will only return properties for public
predicates.</p>
<p>An object’s set of visible predicates is the union of all the predicates
declared for the object with all the built-in methods and all the
Logtalk and Prolog built-in predicates.</p>
<p>The following predicate properties are supported:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">scope(Scope)</span></code></dt><dd><p>The predicate scope (useful for finding the predicate scope with a
single call to <code class="docutils literal notranslate"><span class="pre">predicate_property/2</span></code>)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">public</span></code>, <code class="docutils literal notranslate"><span class="pre">protected</span></code>, <code class="docutils literal notranslate"><span class="pre">private</span></code></dt><dd><p>The predicate scope (useful for testing if a predicate has a
specific scope)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">static</span></code>, <code class="docutils literal notranslate"><span class="pre">dynamic</span></code></dt><dd><p>All predicates are either static or dynamic (note, however, that a
dynamic predicate can only be abolished if it was dynamically
declared)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">logtalk</span></code>, <code class="docutils literal notranslate"><span class="pre">prolog</span></code>, <code class="docutils literal notranslate"><span class="pre">foreign</span></code></dt><dd><p>A predicate can be defined in Logtalk source code, Prolog code, or in
foreign code (e.g., in C)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">built_in</span></code></dt><dd><p>The predicate is a built-in predicate</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">multifile</span></code></dt><dd><p>The predicate is declared multifile (i.e., it can have clauses defined
in multiple files or entities)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">meta_predicate(Template)</span></code></dt><dd><p>The predicate is declared as a meta-predicate with the specified
template</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">coinductive(Template)</span></code></dt><dd><p>The predicate is declared as a coinductive predicate with the
specified template</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">declared_in(Entity)</span></code></dt><dd><p>The predicate is declared (using a scope directive) in the specified
entity</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">defined_in(Entity)</span></code></dt><dd><p>The predicate definition is looked up in the specified entity (note
that this property does not necessarily imply that clauses for the
predicate exist in <code class="docutils literal notranslate"><span class="pre">Entity</span></code>; the predicate can simply be false as
per the <a class="reference internal" href="../glossary.html#term-closed-world-assumption"><span class="xref std std-term">closed-world assumption</span></a>)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">redefined_from(Entity)</span></code></dt><dd><p>The predicate is a redefinition of a predicate definition inherited
from the specified entity</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">non_terminal(NonTerminal//Arity)</span></code></dt><dd><p>The predicate resulted from the compilation of the specified grammar
rule non-terminal</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">alias_of(Predicate)</span></code></dt><dd><p>The predicate (name) is an alias for the specified predicate</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">alias_declared_in(Entity)</span></code></dt><dd><p>The predicate alias is declared in the specified entity</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">synchronized</span></code></dt><dd><p>The predicate is declared as synchronized (i.e., it’s a deterministic
predicate synchronized using a mutex when using a backend Prolog
compiler supporting a compatible multi-threading implementation)</p>
</dd>
</dl>
<p>Some properties are only available when the entities are defined in
source files and when those source files are compiled with the
<a class="reference internal" href="programming.html#flag-source-data"><span class="std std-ref">source_data</span></a> flag turned on:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">recursive</span></code></dt><dd><p>The predicate definition includes at least one recursive rule</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">inline</span></code></dt><dd><p>The predicate definition is inlined</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">auxiliary</span></code></dt><dd><p>The predicate is not user-defined but rather automatically generated
by the compiler or the <a class="reference internal" href="expansion.html#expansion-expansion"><span class="std std-ref">term-expansion mechanism</span></a></p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">mode(Mode,</span> <span class="pre">Solutions)</span></code></dt><dd><p>Instantiation, type, and determinism mode for the predicate (which
can have multiple modes)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">info(ListOfPairs)</span></code></dt><dd><p>Documentation key-value pairs as specified in the user-defined
<code class="docutils literal notranslate"><span class="pre">info/2</span></code> directive</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">number_of_clauses(N)</span></code></dt><dd><p>The number of clauses for the predicate existing at compilation time
(note that this property is not updated at runtime when asserting and
retracting clauses for dynamic predicates)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">number_of_rules(N)</span></code></dt><dd><p>The number of rules for the predicate existing at compilation time
(note that this property is not updated at runtime when asserting and
retracting clauses for dynamic predicates)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">declared_in(Entity,</span> <span class="pre">Line)</span></code></dt><dd><p>The predicate is declared (using a scope directive) in the specified
entity in a source file at the specified line (if applicable)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">defined_in(Entity,</span> <span class="pre">Line)</span></code></dt><dd><p>The predicate is defined in the specified entity in a source file at
the specified line (if applicable)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">redefined_from(Entity,</span> <span class="pre">Line)</span></code></dt><dd><p>The predicate is a redefinition of a predicate definition inherited
from the specified entity, which is defined in a source file at the
specified line (if applicable)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">alias_declared_in(Entity,</span> <span class="pre">Line)</span></code></dt><dd><p>The <a class="reference internal" href="../glossary.html#term-predicate-alias"><span class="xref std std-term">predicate alias</span></a> is declared in the specified entity in a
source file at the specified line (if applicable)</p>
</dd>
</dl>
<p>The properties <code class="docutils literal notranslate"><span class="pre">declared_in/1-2</span></code>, <code class="docutils literal notranslate"><span class="pre">defined_in/1-2</span></code>, and
<code class="docutils literal notranslate"><span class="pre">redefined_from/1-2</span></code> do not apply to built-in methods and Logtalk or
Prolog built-in predicates. Note that if a predicate is declared in a
category imported by the object, it will be the category name — not the
object name — that will be returned by the property <code class="docutils literal notranslate"><span class="pre">declared_in/1</span></code>.
The same is true for protocol declared predicates.</p>
<p>Some properties, such as line numbers, are only available when the entity
holding the predicates is defined in a source file compiled with the
<a class="reference internal" href="programming.html#flag-source-data"><span class="std std-ref">source_data</span></a> flag turned on. Moreover, line
numbers are only supported in <a class="reference internal" href="../glossary.html#term-backend-Prolog-compiler"><span class="xref std std-term">backend Prolog compilers</span></a>
that provide access to the start line of a read term. When such support is
not available, the value <code class="docutils literal notranslate"><span class="pre">-1</span></code> is returned for the start and end lines.</p>
</section>
<section id="finding-declared-predicates">
<span id="predicates-finding"></span><h2>Finding declared predicates<a class="headerlink" href="#finding-declared-predicates" title="Link to this heading"></a></h2>
<p>We can find, by backtracking, all visible user predicates by calling the
<a class="reference internal" href="../refman/methods/current_predicate_1.html#methods-current-predicate-1"><span class="std std-ref">current_predicate/1</span></a> built-in method. This method takes into
account predicate scope declarations. For example, the following call will
only return user predicates that are declared public:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- some_object::current_predicate(Name/Arity).
</pre></div>
</div>
<p>The predicate property <code class="docutils literal notranslate"><span class="pre">non_terminal/1</span></code> may be used to retrieve all
grammar rule non-terminals declared for an object. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>current_non_terminal(<span class="nv">Object</span>, <span class="nv">Name</span><span class="o">//</span><span class="nv">Args</span>) <span class="o">:-</span>
    <span class="nv">Object</span><span class="o">::</span><span class="k">current_predicate</span>(<span class="nv">Name</span><span class="o">/</span><span class="nv">Arity</span>),
    <span class="k">functor</span>(<span class="nv">Predicate</span>, <span class="nv">Functor</span>, <span class="nv">Arity</span>),
    <span class="nv">Object</span><span class="o">::</span><span class="k">predicate_property</span>(<span class="nv">Predicate</span>, non_terminal(<span class="nv">Name</span><span class="o">//</span><span class="nv">Args</span>)).
</pre></div>
</div>
<p>Usually, the non-terminal and the corresponding predicate share the same
functor, but users should not rely on this always being true.</p>
</section>
<section id="calling-prolog-predicates">
<span id="predicates-prolog"></span><h2>Calling Prolog predicates<a class="headerlink" href="#calling-prolog-predicates" title="Link to this heading"></a></h2>
<p>Logtalk is designed for both <em>robustness</em> and <em>portability</em>. In the context
of calling Prolog predicates, robustness requires that the compilation of
Logtalk source code must not have <em>accidental</em> dependencies on Prolog code that
happens to be loaded at the time of the compilation. One immediate consequence
is that only Prolog <em>built-in</em> predicates are visible from within objects and
categories. But Prolog systems provide a widely diverse set of built-in
predicates, easily raising portability issues. Relying on non-standard
predicates is often unavoidable, however, due to the narrow scope of Prolog
standards. Logtalk applications may also require calling user-defined Prolog
predicates, either in <code class="docutils literal notranslate"><span class="pre">user</span></code> or in Prolog modules.</p>
<section id="calling-prolog-built-in-predicates">
<h3>Calling Prolog built-in predicates<a class="headerlink" href="#calling-prolog-built-in-predicates" title="Link to this heading"></a></h3>
<p>In predicate clauses and object <code class="docutils literal notranslate"><span class="pre">initialization/1</span></code> directives, predicate
calls that are not prefixed with a message-sending, super call, or module
qualification operator (<code class="docutils literal notranslate"><span class="pre">::</span></code>, <code class="docutils literal notranslate"><span class="pre">^^</span></code>, or <code class="docutils literal notranslate"><span class="pre">:</span></code>), are compiled to either
calls to local predicates or as calls to Logtalk/Prolog built-in predicates.
A predicate call is compiled as a call to a local predicate if the object
(or category) contains a scope directive, a multifile directive, a dynamic
directive, or a definition for the called predicate. When that is not the
case, the compiler checks if the call corresponds to a Logtalk or Prolog
built-in predicate. Consider the following example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>foo <span class="o">:-</span>
    ...,
    <span class="k">write</span>(bar),
    ...
</pre></div>
</div>
<p>The call to the <code class="docutils literal notranslate"><span class="pre">write/1</span></code> predicate will be compiled as a call to the
corresponding Prolog standard built-in predicate unless the object (or
category) containing the above definition also contains a predicate
named <code class="docutils literal notranslate"><span class="pre">write/1</span></code> or a directive for the predicate.</p>
<p>When calling non-standard Prolog built-in predicates or using non-standard
Prolog arithmetic functions, we may run into portability problems while
trying your applications with different backend Prolog compilers. We can
use the compiler <a class="reference internal" href="programming.html#flag-portability"><span class="std std-ref">portability flag</span></a> to generate
warnings for calls to non-standard predicates and arithmetic functions.
We can also help document those calls using the <a class="reference internal" href="../refman/directives/uses_2.html#directives-uses-2"><span class="std std-ref">uses/2</span></a>
directive. For example, a few Prolog systems provide an <code class="docutils literal notranslate"><span class="pre">atom_string/2</span></code>
non-standard predicate. We can write (in the object or category calling the
predicate):</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">uses</span>(user, [atom_string<span class="o">/</span><span class="m">2</span>])
</pre></div>
</div>
<p>This directive is based on the fact that built-in predicates are visible in
plain Prolog (i.e., in <code class="docutils literal notranslate"><span class="pre">user</span></code>). Besides helping to document the dependency
on a non-standard built-in predicate, this directive will also silence the
compiler portability warning.</p>
</section>
<section id="calling-prolog-non-standard-built-in-meta-predicates">
<span id="predicates-prolog-meta"></span><h3>Calling Prolog non-standard built-in meta-predicates<a class="headerlink" href="#calling-prolog-non-standard-built-in-meta-predicates" title="Link to this heading"></a></h3>
<p>Prolog built-in meta-predicates may only be called locally within
objects or categories, i.e. they cannot be used as messages. Compiling
calls to non-standard, Prolog built-in meta-predicates can be tricky,
however, as there is no standard way of checking if a built-in predicate
is also a meta-predicate and finding out which are its meta-arguments.
But Logtalk supports overriding the original meta-predicate template
when not programmatically available or usable. For example, assume a
<code class="docutils literal notranslate"><span class="pre">det_call/1</span></code> Prolog built-in meta-predicate that takes a goal as
argument. We can add to the object (or category) calling it the
directive:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">meta_predicate</span>(user<span class="o">::</span>det_call(<span class="m">0</span>)).
</pre></div>
</div>
<p>Another solution is to explicitly declare non-standard built-in Prolog
meta-predicates in the corresponding adapter file using the internal
predicate <code class="docutils literal notranslate"><span class="pre">'$lgt_prolog_meta_predicate'/3</span></code>. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="s">&#39;$lgt_prolog_meta_predicate&#39;</span>(det_call(<span class="nv">_</span>), det_call(<span class="m">0</span>), predicate).
</pre></div>
</div>
<p>The third argument can be either the atom <code class="docutils literal notranslate"><span class="pre">predicate</span></code> or the atom
<code class="docutils literal notranslate"><span class="pre">control_construct</span></code>, a distinction that is useful when compiling in
debug mode.</p>
</section>
<section id="calling-prolog-foreign-predicates">
<span id="predicates-prolog-foreign"></span><h3>Calling Prolog foreign predicates<a class="headerlink" href="#calling-prolog-foreign-predicates" title="Link to this heading"></a></h3>
<p>Prolog systems often support defining <cite>foreign</cite> predicates, i.e. predicates
defined using languages other than Prolog using a <cite>foreign language interface</cite>.
There isn’t, however, any standard for defining, making available, and
recognizing foreign predicates. From a Logtalk perspective, the two most
common scenarios are calling a foreign predicate (from within an object or a
category) and making a set of foreign predicates available as part of an
object (or category) protocol. Assuming, as this is the most common case,
that foreign predicates are globally visible once made available (using a
Prolog system-specific loading or linking procedure), we can simply call
them as user-defined plain predicates, as explained in the next section.
When defining an object (or category) that makes available foreign
predicates, the advisable solution is to name the predicates after the
object (or category) and then define object (or category) predicates that
call the foreign predicates. Most backend adapter files include support for
recognizing foreign predicates that allows the Logtalk compiler to inline
calls to the predicates (thus avoiding call indirection overheads).</p>
</section>
<section id="calling-prolog-user-defined-plain-predicates">
<span id="predicates-prolog-user"></span><h3>Calling Prolog user-defined plain predicates<a class="headerlink" href="#calling-prolog-user-defined-plain-predicates" title="Link to this heading"></a></h3>
<p>User-defined Prolog plain predicates (i.e., predicates that are not defined
in a Prolog module) can be called from within objects or categories by
sending the corresponding message to <code class="docutils literal notranslate"><span class="pre">user</span></code>. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>foo <span class="o">:-</span>
    ...,
    user<span class="o">::</span>bar,
    ...
</pre></div>
</div>
<p>In alternative, we can use the <a class="reference internal" href="../refman/directives/uses_2.html#directives-uses-2"><span class="std std-ref">uses/2</span></a> directive and write:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">uses</span>(user, [bar<span class="o">/</span><span class="m">0</span>]).

foo <span class="o">:-</span>
    ...,
    bar,
    ...
</pre></div>
</div>
<p>Note that <code class="docutils literal notranslate"><span class="pre">user</span></code> is a pseudo-object in Logtalk containing all predicate
definitions that are not encapsulated (either in a Logtalk entity or a
Prolog module).</p>
<p>When the Prolog predicate is not a meta-predicate, we can also use the
<a class="reference internal" href="../refman/control/external_call_1.html#control-external-call-1"><span class="std std-ref">{}/1</span></a> compiler bypass control construct. For
example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>foo <span class="o">:-</span>
    ...,
    <span class="k">{</span>bar<span class="k">}</span>,
    ...
</pre></div>
</div>
<p>But note that in this case the <a class="reference internal" href="reflection.html#reflection-reflection"><span class="std std-ref">reflection API</span></a>
will not record the dependency of the <code class="docutils literal notranslate"><span class="pre">foo/0</span></code> predicate on the Prolog
<code class="docutils literal notranslate"><span class="pre">bar/0</span></code> predicate as we are effectively bypassing the compiler.</p>
</section>
<section id="calling-prolog-module-predicates">
<span id="predicates-prolog-module"></span><h3>Calling Prolog module predicates<a class="headerlink" href="#calling-prolog-module-predicates" title="Link to this heading"></a></h3>
<p>Prolog module predicates can be called from within objects or categories by
using explicit qualification. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>foo <span class="o">:-</span>
    ...,
    module<span class="o">:</span>bar,
    ...
</pre></div>
</div>
<p>You can also use the <a class="reference internal" href="../refman/directives/use_module_2.html#directives-use-module-2"><span class="std std-ref">use_module/2</span></a> directive
to call the module predicates using implicit qualification:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">use_module</span>(module, [bar<span class="o">/</span><span class="m">0</span>]).

foo <span class="o">:-</span>
    ...,
    bar,
    ...
</pre></div>
</div>
<p>Note that the first argument of the <code class="docutils literal notranslate"><span class="pre">use_module/2</span></code> directive, when used
within an object or a category, is a <em>module name</em>, not a <em>file specification</em>
(also be aware that Prolog modules are sometimes defined in files with names
that differ from the module names).</p>
<p>As loading a Prolog module varies between Prolog systems, the actual loading
directive or goal is preferably done from the application <a class="reference internal" href="../glossary.html#term-loader-file"><span class="xref std std-term">loader file</span></a>.
An advantage of this approach is that it contributes to a clean separation
between <em>loading</em> and <em>using</em> a resource, with the loader file being the
central point that loads all application resources (complex applications
often use a <em>hierarchy</em> of loader files, but the main idea remains the same).</p>
<p>As an example, assume that we need to call predicates defined in a CLP(FD)
Prolog library, which can be loaded using <code class="docutils literal notranslate"><span class="pre">library(clpfd)</span></code> as the file
specification. In the loader file, we would add:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">use_module</span>(library(clpfd), []).
</pre></div>
</div>
<p>Specifying an empty import list is often used to avoid adding the
module-exported predicates to plain Prolog. In the objects and categories we
can then call the library predicates, using implicit or explicit qualification,
as explained. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(puzzle).

<span class="p">    :- </span><span class="k">public</span>(puzzle<span class="o">/</span><span class="m">1</span>).

<span class="p">    :- </span><span class="k">use_module</span>(clpfd, [
        all_different<span class="o">/</span><span class="m">1</span>, ins<span class="o">/</span><span class="m">2</span>, label<span class="o">/</span><span class="m">1</span>,
        (<span class="err">#</span><span class="o">=</span>)<span class="o">/</span><span class="m">2</span>, (<span class="err">#</span><span class="o">\=</span>)<span class="o">/</span><span class="m">2</span>,
        <span class="k">op</span>(<span class="m">700</span>, xfx, <span class="err">#</span><span class="o">=</span>), <span class="k">op</span>(<span class="m">700</span>, xfx, <span class="err">#</span><span class="o">\=</span>)
    ]).

    puzzle([<span class="nv">S</span>,<span class="nv">E</span>,<span class="nv">N</span>,<span class="nv">D</span>] <span class="o">+</span> [<span class="nv">M</span>,<span class="nv">O</span>,<span class="nv">R</span>,<span class="nv">E</span>] <span class="o">=</span> [<span class="nv">M</span>,<span class="nv">O</span>,<span class="nv">N</span>,<span class="nv">E</span>,<span class="nv">Y</span>]) <span class="o">:-</span>
        <span class="nv">Vars</span> <span class="o">=</span> [<span class="nv">S</span>,<span class="nv">E</span>,<span class="nv">N</span>,<span class="nv">D</span>,<span class="nv">M</span>,<span class="nv">O</span>,<span class="nv">R</span>,<span class="nv">Y</span>],
        <span class="nv">Vars</span> ins <span class="m">0.</span>.<span class="m">9</span>,
        all_different(<span class="nv">Vars</span>),
                  <span class="nv">S</span><span class="o">*</span><span class="m">1000</span> <span class="o">+</span> <span class="nv">E</span><span class="o">*</span><span class="m">100</span> <span class="o">+</span> <span class="nv">N</span><span class="o">*</span><span class="m">10</span> <span class="o">+</span> <span class="nv">D</span> <span class="o">+</span>
                  <span class="nv">M</span><span class="o">*</span><span class="m">1000</span> <span class="o">+</span> <span class="nv">O</span><span class="o">*</span><span class="m">100</span> <span class="o">+</span> <span class="nv">R</span><span class="o">*</span><span class="m">10</span> <span class="o">+</span> <span class="nv">E</span> <span class="err">#</span><span class="o">=</span>
        <span class="nv">M</span><span class="o">*</span><span class="m">10000</span> <span class="o">+</span> <span class="nv">O</span><span class="o">*</span><span class="m">1000</span> <span class="o">+</span> <span class="nv">N</span><span class="o">*</span><span class="m">100</span> <span class="o">+</span> <span class="nv">E</span><span class="o">*</span><span class="m">10</span> <span class="o">+</span> <span class="nv">Y</span>,
        <span class="nv">M</span> <span class="err">#</span><span class="o">\=</span> <span class="m">0</span>, <span class="nv">S</span> <span class="err">#</span><span class="o">\=</span> <span class="m">0</span>,
        label([<span class="nv">M</span>,<span class="nv">O</span>,<span class="nv">N</span>,<span class="nv">E</span>,<span class="nv">Y</span>]).

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The actual module code <strong>must</strong> be loaded prior to the compilation of
Logtalk source code that uses it. In particular, programmers should
not expect that the module be auto-loaded (including when using a
backend Prolog compiler that supports an auto-loading mechanism).</p>
</div>
<p>The module identifier argument can also be a <a class="reference internal" href="../glossary.html#term-parameter-variable"><span class="xref std std-term">parameter variable</span></a>
when using the directive in a parametric object or a parametric category.
In this case, dynamic binding will necessarily be used for all listed
predicates (and non-terminals). The parameter variable must be instantiated
at runtime when the calls are made.</p>
<p>Logtalk supports the declaration of <a class="reference internal" href="../glossary.html#term-predicate-alias"><span class="xref std std-term">predicate aliases</span></a>
and <a class="reference internal" href="../glossary.html#term-predicate-shorthand"><span class="xref std std-term">predicate shorthands</span></a> in <code class="docutils literal notranslate"><span class="pre">use_module/2</span></code>
directives used within objects and categories. For example, the ECLiPSe IC
Constraint Solvers define a <code class="docutils literal notranslate"><span class="pre">(::)/2</span></code> variable domain operator that clashes
with the Logtalk <code class="docutils literal notranslate"><span class="pre">(::)/2</span></code> message-sending operator. We can solve the conflict
by writing:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">use_module</span>(ic, [(<span class="o">::</span>)<span class="o">/</span><span class="m">2</span> <span class="o">as</span> ins<span class="o">/</span><span class="m">2</span>]).
</pre></div>
</div>
<p>With this directive, calls to the <code class="docutils literal notranslate"><span class="pre">ins/2</span></code> predicate alias will be
automatically compiled by Logtalk to calls to the <code class="docutils literal notranslate"><span class="pre">(::)/2</span></code> predicate in
the <code class="docutils literal notranslate"><span class="pre">ic</span></code> module.</p>
</section>
<section id="calling-prolog-module-meta-predicates">
<span id="predicates-prolog-module-meta-predicates"></span><h3>Calling Prolog module meta-predicates<a class="headerlink" href="#calling-prolog-module-meta-predicates" title="Link to this heading"></a></h3>
<p>The Logtalk library provides implementations of common meta-predicates,
which can be used in place of module meta-predicates (e.g., list mapping
meta-predicates). If that is not the case, the Logtalk compiler may need
help to understand the module meta-predicate templates. Despite some recent
progress in standardization of the syntax of <code class="docutils literal notranslate"><span class="pre">meta_predicate/1</span></code> directives
and of the <code class="docutils literal notranslate"><span class="pre">meta_predicate/1</span></code> property returned by the <code class="docutils literal notranslate"><span class="pre">predicate_property/2</span></code>
reflection predicate, portability is still a major problem. Thus, Logtalk
allows the original <code class="docutils literal notranslate"><span class="pre">meta_predicate/1</span></code> directive to be <strong>overridden</strong>
with a local directive that Logtalk can make sense of. It also allows
providing a <code class="docutils literal notranslate"><span class="pre">meta_predicate/1</span></code> directive when it’s missing from the module
defining the meta-predicate. Note that Logtalk is not based on a predicate
prefixing mechanism as found in module systems. This fundamental difference
precludes an automated solution at the Logtalk compiler level.</p>
<p>As an example, assume that you want to call from an object (or a category)
a module meta-predicate with the following meta-predicate directive:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">module</span>(foo, [bar<span class="o">/</span><span class="m">2</span>]).

<span class="p">:- </span><span class="k">meta_predicate</span>(bar(<span class="o">*</span>, <span class="o">:</span>)).
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">:</span></code> meta-argument specifier is ambiguous. It tell us that the second
argument of the meta-predicate is module sensitive, but it does not tell us
<em>how</em>. Some legacy module libraries and some Prolog systems use <code class="docutils literal notranslate"><span class="pre">:</span></code> to
mean <code class="docutils literal notranslate"><span class="pre">0</span></code> (i.e., a meta-argument that will be meta-called). Some others
use <code class="docutils literal notranslate"><span class="pre">:</span></code> for meta-arguments that are not meta-called but that still need
to be augmented with module information. Whichever the case, the Logtalk
compiler doesn’t have enough information to unambiguously parse the
directive and correctly compile the  meta-arguments in the meta-predicate
call. Therefore, the Logtalk compiler will generate an error stating that
<code class="docutils literal notranslate"><span class="pre">:</span></code> is not a valid meta-argument specifier when trying to compile a
<code class="docutils literal notranslate"><span class="pre">foo:bar/2</span></code> goal. There are two alternative solutions for this problem.
The advised solution is to override the meta-predicate directive by writing,
inside the object (or category) where the meta-predicate is called:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">meta_predicate</span>(foo<span class="o">:</span>bar(<span class="o">*</span>, <span class="o">*</span>)).
</pre></div>
</div>
<p>or:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">meta_predicate</span>(foo<span class="o">:</span>bar(<span class="o">*</span>, <span class="m">0</span>)).
</pre></div>
</div>
<p>depending on the true meaning of the second meta-argument. The second
alternative, only usable when the meta-argument can be handled as a
normal argument, is to simply use the <a class="reference internal" href="../refman/control/external_call_1.html#control-external-call-1"><span class="std std-ref">{}/1</span></a>
compiler bypass control construct to call the meta-predicate as-is:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>... <span class="o">:-</span> <span class="k">{</span>foo<span class="o">:</span>bar(..., ...)<span class="k">}</span>, ...
</pre></div>
</div>
<p>The downside of this alternative is that it hides the dependency on the
module library from the reflection API and thus from the developer tools.</p>
</section>
</section>
<section id="defining-prolog-multifile-predicates">
<span id="predicates-prolog-multifile"></span><h2>Defining Prolog multifile predicates<a class="headerlink" href="#defining-prolog-multifile-predicates" title="Link to this heading"></a></h2>
<p>Some Prolog module libraries, e.g. constraint packages, expect clauses
for some library predicates to be defined in other modules. This is
accomplished by declaring the library predicate <em>multifile</em> and by
explicitly prefixing predicate clause heads with the library module
identifier. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">multifile</span>(clpfd<span class="o">:</span>run_propagator<span class="o">/</span><span class="m">2</span>).
clpfd<span class="o">:</span>run_propagator(..., ...) <span class="o">:-</span>
    ...
</pre></div>
</div>
<p>Logtalk supports the definition of Prolog module multifile predicates in
objects and categories. While the clause head is compiled as-is, the clause
body is compiled in the same way as a regular object or category predicate,
thus allowing calls to local object or category predicates. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(...).

<span class="p">    :- </span><span class="k">multifile</span>(clpfd<span class="o">:</span>run_propagator<span class="o">/</span><span class="m">2</span>).
    clpfd<span class="o">:</span>run_propagator(..., ...) <span class="o">:-</span>
        <span class="c">% calls to local object predicates</span>
        ...

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>The Logtalk compiler will print a warning if the <code class="docutils literal notranslate"><span class="pre">multifile/1</span></code>
directive is missing. These multifile predicates may also be declared
dynamic using the same <code class="docutils literal notranslate"><span class="pre">Module:Name/Arity</span></code> notation.</p>
</section>
<section id="asserting-and-retracting-prolog-predicates">
<span id="predicates-prolog-dynamic"></span><h2>Asserting and retracting Prolog predicates<a class="headerlink" href="#asserting-and-retracting-prolog-predicates" title="Link to this heading"></a></h2>
<p>To assert and retract clauses for Prolog dynamic predicates, we can use an
explicitly qualified module argument. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(...).

<span class="p">    :- </span><span class="k">dynamic</span>(m<span class="o">:</span>bar<span class="o">/</span><span class="m">1</span>).

    foo(<span class="nv">X</span>) <span class="o">:-</span>
        <span class="k">retractall</span>(m<span class="o">:</span>bar(<span class="nv">_</span>)),
        <span class="k">assertz</span>(m<span class="o">:</span>bar(<span class="nv">X</span>)),
        ...

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>In alternative, we can use <a class="reference internal" href="../refman/directives/use_module_2.html#directives-use-module-2"><span class="std std-ref">use_module/2</span></a>
directives to declare the module predicates. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(...).

<span class="p">    :- </span><span class="k">use_module</span>(m, [bar<span class="o">/</span><span class="m">1</span>]).
<span class="p">    :- </span><span class="k">dynamic</span>(m<span class="o">:</span>bar<span class="o">/</span><span class="m">1</span>).

    foo(<span class="nv">X</span>) <span class="o">:-</span>
        <span class="c">% retract and assert bar/1 clauses in module m</span>
        <span class="k">retractall</span>(bar(<span class="nv">_</span>)),
        <span class="k">assertz</span>(bar(<span class="nv">X</span>)),
        ...

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>When the Prolog dynamic predicates are defined in <code class="docutils literal notranslate"><span class="pre">user</span></code>, the recommended
and most portable practice (as not all backends support a module system) is
to use a <a class="reference internal" href="../refman/directives/uses_2.html#directives-uses-2"><span class="std std-ref">uses/2</span></a> directive:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(...).

<span class="p">    :- </span><span class="k">uses</span>(user, [bar<span class="o">/</span><span class="m">1</span>]).
<span class="p">    :- </span><span class="k">dynamic</span>(user<span class="o">::</span>bar<span class="o">/</span><span class="m">1</span>).

    foo(<span class="nv">X</span>) <span class="o">:-</span>
        <span class="c">% retract and assert bar/1 clauses in user</span>
        <span class="k">retractall</span>(bar(<span class="nv">_</span>)),
        <span class="k">assertz</span>(bar(<span class="nv">X</span>)),
        ...

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Note that in the alternatives using <code class="docutils literal notranslate"><span class="pre">uses/2</span></code> or <code class="docutils literal notranslate"><span class="pre">use_module/2</span></code> directives,
the argument of the database handling predicates must be known at compile-time.
If that is not the case, you must use either an explicitly-qualified argument
or the <a class="reference internal" href="../refman/control/external_call_1.html#control-external-call-1"><span class="std std-ref">{}/1</span></a> control construct instead. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(...).

    add(<span class="nv">X</span>) <span class="o">:-</span>
        <span class="c">% assert clause X in module m</span>
        <span class="k">assertz</span>(m<span class="o">:</span><span class="nv">X</span>),
        ...

    remove(<span class="nv">Y</span>) <span class="o">:-</span>
        <span class="c">% retract all clauses in user whose head unifies with Y</span>
        <span class="k">{retractall</span>(<span class="nv">Y</span>)<span class="k">}</span>,
        ...

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="categories.html" class="btn btn-neutral float-left" title="Categories" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="inheritance.html" class="btn btn-neutral float-right" title="Inheritance" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 1998-2025, Paulo Moura.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>